在没有真实CardDAV服务器的本地或持续集成环境中，要验证联系人同步逻辑往往需要在代码里硬编码一堆假数据，或者费尽周折去连接一个公网测试账户。这些方式不但效率低下，还很难覆盖协议的各种边界情况，比如集合同步标记、多地址簿切换等。本篇文章将带你用Node.js从零搭建一个CardDAV Mock服务，并在此基础上实现 Mock2Image 功能——自动将联系人信息转化为专属头像，让测试联系人列表看起来不再是一串枯燥的字符串。
CardDAV协议要点与Mock服务的核心需求
要模拟一个CardDAV服务器，首先要理解客户端会发起哪些 HTTP 请求。CardDAV 本质上是建立在 WebDAV 之上的扩展，主要涉及 PROPFIND、REPORT、GET 和 PUT 等方法。客户端通常会先向地址簿集合的 URL 发起 PROPFIND 请求，获取所有地址簿资源列表，然后通过 REPORT 请求执行 addressbook-query 来查询符合条件的联系人。每个联系人实体都以 vCard 格式返回，其中可以包含姓名、电话、邮箱甚至头像照片的二进制数据。
Mock 服务需要满足几个基本要求：能够响应正确的 HTTP 状态码和 XML 响应体；支持在内存或本地文件中预设若干虚拟联系人；提供多种查询参数的解析，例如基于 limit 或 filter 的条件筛选；还要保证每次重启后的数据一致性。如果只是做简单的 GET 请求返回静态 vCard 文件，那还算不上真正意义上的 Mock，因为无法验证客户端是否正确构造了 REPORT 请求体。因此我们需要解析 XML 请求，识别出关键元素如 C:address-data，并动态生成对应的 vCard 内容再封装进标准的 D:multistatus 响应结构里。
另一个容易被忽略的点是 sync-token 同步机制。真实的 CardDAV 服务会通过 sync-collection 报文支持增量同步，客户端只拉取自上次同步后变化的联系人。Mock 服务如果想模拟完整的同步流程，也需要维护一个简单的 token 映射，当 REPORT 请求带有 sync-token 时，返回基于该 token 之后发生变更的联系人。不过对初期联调而言，可以先实现全量返回，待基础功能稳定后再迭代增量同步逻辑。
出于测试便利性，Mock 服务还应该提供管理接口，比如通过 REST API 动态添加、删除或修改联系人数据，这样测试同学不必每次都去改代码或配置文件。这些辅助接口可以仅在内网或本地开放，不影响主 CardDAV 协议路径。
基于Node.js搭建CardDAV Mock Server
我们选择一个轻量的 HTTP 框架，比如 Express 或 Fastify，来处理请求路由。为了解析 XML 请求体，需要引入 body-parser 的 XML 中间件，或者直接用 express-xml-bodyparser 这类包。同时，为了生成合法的 WebDAV XML 响应，可以借助 xmlbuilder2 或 xml2js 来构建输出。下面是一个简化版的服务骨架，监听 /carddav/ 路径，对 PROPFIND 和 REPORT 请求进行处理：
const express = require('express');
const xmlparser = require('express-xml-bodyparser');
const { create } = require('xmlbuilder2');
const app = express();
app.use(xmlparser());
// 内存中的联系人数据
const contacts = [
{ uid: '1', fullname: '张三', email: 'zhangsan@ipipp.com', phone: '13800138000' },
{ uid: '2', fullname: '李四', email: 'lisi@ipipp.com', phone: '13900139000' }
];
// 处理 PROPFIND 请求
app.propfind('/carddav/', (req, res) => {
const multistatus = create({ version: '1.0', encoding: 'UTF-8' })
.ele('D:multistatus', { 'xmlns:D': 'DAV:', 'xmlns:C': 'urn:ietf:params:xml:ns:carddav' });
contacts.forEach(contact => {
multistatus.ele('D:response')
.ele('D:href').txt('/carddav/' + contact.uid + '.vcf').up()
.ele('D:propstat')
.ele('D:prop')
.ele('D:getetag').txt('"' + contact.uid + '-etag"').up()
.ele('C:address-data').txt('BEGIN:VCARDrnVERSION:3.0rnFN:' + contact.fullname + 'rnEND:VCARD').up()
.up()
.ele('D:status').txt('HTTP/1.1 200 OK').up()
.up()
.up();
});
res.status(207).set('Content-Type', 'application/xml; charset=utf-8').send(multistatus.end());
});
// 处理 REPORT 请求
app.report('/carddav/', (req, res) => {
const body = req.body;
// 简化的处理：直接返回全部联系人
const multistatus = create({ version: '1.0', encoding: 'UTF-8' })
.ele('D:multistatus', { 'xmlns:D': 'DAV:', 'xmlns:C': 'urn:ietf:params:xml:ns:carddav' });
contacts.forEach(contact => {
multistatus.ele('D:response')
.ele('D:href').txt('/carddav/' + contact.uid + '.vcf').up()
.ele('D:propstat')
.ele('D:prop')
.ele('C:address-data').txt('BEGIN:VCARDrnVERSION:3.0rnFN:' + contact.fullname + 'rnEND:VCARD').up()
.up()
.ele('D:status').txt('HTTP/1.1 200 OK').up()
.up()
.up();
});
res.status(207).set('Content-Type', 'application/xml; charset=utf-8').send(multistatus.end());
});
app.listen(3000, () => console.log('CardDAV Mock Server running on port 3000'));
以上代码展示了最基础的响应结构。实际应用中，我们需要解析 REPORT 请求中的 addressbook-query 元素，提取可能的过滤条件（比如 prop-filter），然后只返回匹配的联系人。另外，响应中的 getetag 和 href 应当保证唯一性和可追溯性。对于 PROPFIND，通常客户端会指定 Depth 头部，Mock 服务也需要根据 Depth: 1 返回地址簿下一级的资源列表，这里为了简洁省略了对此的判断，但在实际测试中建议补全。
针对 vCard 的返回，可以直接构造文本字符串，如示例中的简单格式。但如果联系人属性较多，比如包含多个电话号码、地址等，建议使用 vcard4 或 vcf 这类 npm 包来生成规范的 vCard 数据，避免手动拼接时格式错误。同时，响应体中的 XML 需要正确转义 vCard 内容中的特殊字符，比如 & 应替换为 &，否则会导致 XML 解析失败。
为了让 Mock 服务更贴近真实环境，我们还可以实现 OPTIONS 请求，返回服务器支持的 DAV 功能头，比如 DAV: 1, 2, 3, addressbook，这样客户端在探测阶段就不会因为缺少声明的能力而放弃通信。这些细节虽然不影响核心逻辑，却能有效避免客户端集成时的各种怪异问题。
实现Mock2Image：联系人头像的自动生成策略
Mock2Image 的核心思路是：为每一个联系人自动生成一张具有辨识度的头像图片，并在 vCard 中通过 PHOTO 属性或外链 URL 的形式暴露给客户端。这样，前端在展示联系人列表时可以立即看到个性化的圆形头像，而不再是一片默认的灰色占位图。生成策略通常有两种：基于姓名首字母的计算生成和基于随机色彩的 SVG 绘制。
基于首字母的方案最简洁有效。我们可以使用 Node.js 的 Canvas 库（如 canvas npm 包）或纯 SVG 来实现。考虑到跨平台兼容性和构建依赖的复杂性，推荐使用 SVG 转 Data URI 的方式：根据联系人的 FN 字段提取首字符（英文取首字母，中文可取拼音首字母或直接使用“姓”），然后随机生成背景色，确保文本颜色对比度足够。这样生成的 SVG 可以直接作为 data:image/svg+xml;utf8,... 嵌入 vCard 的 PHOTO 属性中，或者单独通过一个 HTTP 端点暴露出去。
另一种增强体验的做法是为每个联系人分配一组固定的几何图案或渐变背景，避免仅仅依赖首字母导致视觉单调。比如根据 UID 的哈希值决定背景的圆形、方形组合，这样即使首字母相同的联系人也能够区分开来。下面是利用 canvas 模块生成带首字母头像的示例代码：
const { createCanvas } = require('canvas');
function generateAvatar(fullname, size = 128) {
const canvas = createCanvas(size, size);
const ctx = canvas.getContext('2d');
// 随机背景色
const hue = Math.floor(Math.random() * 360);
ctx.fillStyle = `hsl(${hue}, 70%, 60%)`;
ctx.fillRect(0, 0, size, size);
// 首字母
const initial = fullname.charAt(0).toUpperCase();
ctx.fillStyle = '#ffffff';
ctx.font = `bold ${size * 0.5}px Arial`;
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(initial, size / 2, size / 2);
return canvas.toDataURL('image/png');
}
在 vCard 中嵌入头像照片时，可以直接把 data:image/png;base64,... 放入 PHOTO;ENCODING=b: 字段，或者采用 PHOTO;VALUE=URL 指向 Mock 服务提供的独立头像 URL。后者更推荐，因为不会让 vCard 体积过于膨胀，也便于前端缓存。我们可以在服务器中增加一个路由 /avatar/:uid，先检查是否有预先生成的图片，否则动态调用生成函数并缓冲结果。
需要注意，当客户端请求联系人时，如果 vCard 中的 PHOTO 使用了 URL 形式，应当返回可公开访问的绝对路径，例如 http://localhost:3000/avatar/1.png。并且在 PROPFIND 或 REPORT 的响应里，C:address-data 中包含的 vCard 文本就应该带有这个 URL。为此，我们需要在构造 vCard 字符串时动态插入该字段。有了 Mock2Image，整个地址簿的可视化效果得到质的提升，便于测试人员快速识别条目，也更容易演示原型。
集成测试与扩展思路
完成上述两个部分后，我们就可以启动服务，用任何支持 CardDAV 的客户端（如系统通讯录、Thunderbird 等）连接 http://localhost:3000/carddav/ 进行验证。在 Mac 或 iOS 上添加 CardDAV 账户时，输入服务器地址和路径，即可看到预设的联系人列表，每个联系人的头像也会自动展示出来。此时我们还能观察客户端发起的实际请求，进一步完善 Mock 响应中的细节，比如加入 sync-token 支持或分页查询。
Mock2Image 的思路同样可以扩展到为企业内部测试环境生成更丰富的虚拟数据。例如结合 Faker.js 生成包含地址、公司、生日等信息的完整 vCard，并为每个联系人自动分配一个与部门相关的头像底色。还可以将 Mock 服务容器化，通过环境变量控制联系人的数量和属性，适配不同的性能测试场景。把 Mock 服务集成进 CI 流水线后，每次提交都会自动验证联系人同步模块的行为，真正做到“零依赖测试”。
对于希望深入了解 WebDAV 和 CardDAV 协议的开发者，这个 Mock 服务也是一个很好的学习工具。你可以逐步增加对 MKCALENDAR、ACL 等扩展的支持，甚至实现简单的权限验证，模拟多用户场景。Node.js 的异步特性和丰富的中间件生态，让我们能够快速构建出既能满足测试需求，又具备一定教育意义的协议模拟环境。