如何用 Node.js 实现 ScyllaDB Mock2Image 并自动生成数据快照？

在 Node.js 里做 ScyllaDB 相关测试时，经常会遇到一个尴尬：mock 数据已经准备好了，但团队里其他人想快速确认这张表长什么样，只能去翻代码或查看 JSON 输出。如果能把 mock 结果直接渲染成图片，嵌入到 CI 报告或 PR 描述里，沟通成本会低很多。ScyllaDBMock2Image 就是围绕这个目标设计的轻量工具，核心思路是读取模拟 rows，按列名和类型生成表格图片。

一、直接从 Mock 数据源入手

真实场景里，ScyllaDB 测试通常不会连接生产集群，而是通过内存态模拟或者预置的 cassandra-driver mock 来提供 rows。Node.js 的 cassandra-driver 允许自定义 Client 的行为，例如在单测里把 execute 方法替换成固定返回。这样就能在不依赖网络的情况下产出稳定的查询结果。实现 Mock2Image 的第一步是把这些结果抽成统一结构。

建议先定义一个中间表示，包含表名、主键列、普通列和示例数据。不要直接在驱动返回的 Row 对象上做字符串拼接，因为 Row 的字段可能包含 UDT、集合甚至 null。转换成普通对象后，后续绘图逻辑会简单很多。下面是一段模拟 ScyllaDB 查询结果的代码，供后续生成图片使用。

const mockRows = [
  { id: 'a1f2c3', name: 'order-service', status: 'active', qps: 18400, tags: ['api', 'edge'] },
  { id: 'b4e5d6', name: 'payment-worker', status: 'idle', qps: 3200, tags: ['batch'] },
  { id: 'c7a8b9', name: 'report-job', status: 'paused', qps: 0, tags: [] },
];

function normalizeRows(rows, primaryKeys) {
  return rows.map((row) => {
    const normalized = {};
    for (const key of Object.keys(row)) {
      const value = row[key];
      if (Array.isArray(value)) {
        normalized[key] = value.join(', ');
      } else if (value === null || value === undefined) {
        normalized[key] = 'null';
      } else {
        normalized[key] = String(value);
      }
    }
    normalized.__isPrimary = primaryKeys.includes(row.id);
    return normalized;
  });
}

module.exports = { mockRows, normalizeRows };

上面代码里 normalizeRows 的作用是把数组、空值统一成字符串，并额外标记主键，便于后续在图片中加粗或添加底色。如果直接用 row.id 判断主键，记得主键可能是复合键，需要把传入的 primaryKeys 设计成数组。

这个中间层还可以扩展类型信息。比如从 ScyllaDB 的 system_schema.columns 读取字段的 type，或者直接从 mock 配置里读取。图片里如果能展示 int、text、list 等类型，对阅读者会更友好。

二、用 SVG 生成图片比 Canvas 更轻量

生成图片有两条路线：使用 node-canvas 直接绘制 PNG，或者拼装 SVG 字符串后交给 sharp 转换成 PNG。对于表格快照，SVG 更适合，因为文本可搜索、可缩放，而且不依赖原生编译模块。Node.js 端只需要根据 rows 计算列宽和行高，生成对应的 <rect> 和 <text> 元素。

列宽计算不能只按表头长度，还要遍历所有行取最长内容，否则某些长字符串会被截断。字符宽度可以按英文等宽估算，中文按两个单位处理。以下函数根据列内容估算每一列的像素宽度，并生成横向布局。

function estimateColumnWidths(headers, rows) {
  const minWidth = 80;
  const charWidth = 7.2;
  return headers.map((header, colIndex) => {
    let maxText = header;
    for (const row of rows) {
      const cell = row[header] || '';
      if (String(cell).length > String(maxText).length) {
        maxText = cell;
      }
    }
    const estimated = String(maxText).length * charWidth + 24;
    return Math.max(estimated, minWidth);
  });
}

function buildSvg(headers, rows, widths) {
  const rowHeight = 32;
  const headerHeight = 40;
  const tableWidth = widths.reduce((sum, w) => sum + w, 0);
  const tableHeight = headerHeight + rows.length * rowHeight;
  let y = headerHeight;
  let body = '';
  for (const row of rows) {
    let x = 0;
    for (let i = 0; i < headers.length; i++) {
      const value = row[headers[i]] || '';
      body += `<rect x="${x}" y="${y}" width="${widths[i]}" height="${rowHeight}" fill="none" stroke="#d0d7de"/>`;
      body += `<text x="${x + 10}" y="${y + 20}" font-size="13" fill="#24292f">${escapeXml(value)}</text>`;
      x += widths[i];
    }
    y += rowHeight;
  }
  return `<svg xmlns="http://www.w3.org/2000/svg" width="${tableWidth}" height="${tableHeight}" viewBox="0 0 ${tableWidth} ${tableHeight}">${body}</svg>`;
}

function escapeXml(value) {
  return String(value)
    .replace(/&/g, '&')
    .replace(/</g, '<')
    .replace(/>/g, '>')
    .replace(/"/g, '"');
}

需要注意 buildSvg 里的模板字符串不能直接插入未转义的用户数据，否则包含 < 或 & 的单元格会破坏 XML 结构。上面的 escapeXml 已经处理了这些情况。

如果不需要 PNG，直接把 SVG 写到 .svg 文件就能在浏览器和 GitHub 中预览。若要生成 PNG，可以用 sharp 的 sharp(Buffer.from(svg)).png().toFile(...)，不需要安装 canvas 依赖。

三、处理 ScyllaDB 的集合类型和宽表

ScyllaDB 的表经常包含 list、set、map 以及 frozen 字段。如果把集合直接 String() 化，会出现类似 [object Object] 的无效信息。在 normalize 阶段就应该针对集合递归展开。对于 list 和 set，可以用逗号加空格拼接；对于 map，可以按 key: value 的格式逐项展示。

宽表是另一个难题。如果一个表有几十列，生成的图片宽度可能超过 3000 像素，在报告中会被缩放得看不清。可以在生成图片前设置最大宽度，超过时只渲染前 N 列，并在末尾添加一列省略提示。也可以按列族拆分，生成多张图片，例如将静态列和动态列分开。

function formatComplexValue(value) {
  if (value === null || value === undefined) return 'null';
  if (Array.isArray(value)) return value.map(formatComplexValue).join(', ');
  if (typeof value === 'object') {
    return Object.entries(value)
      .map(([k, v]) => `${k}: ${formatComplexValue(v)}`)
      .join('; ');
  }
  return String(value);
}

这段代码的核心是递归处理对象和数组。ScyllaDB 的 map 类型在驱动里通常被解析为 JavaScript 对象，所以直接 Object.entries 即可。但如果值是 Long 类型，需要先调用 value.toString()，避免出现精度问题。

四、接入 CI 和测试流程

Mock2Image 的价值要在自动化流程中体现。可以在测试套件的 afterEach 或专门的快照测试里调用生成函数，把图片写入 artifacts/scylla-mock 目录。CI 平台（如 GitHub Actions、Jenkins）可以把这个目录作为构建产物上传，失败时开发者直接点开图片就能看到当时的数据状态。

为了减少重复生成，可以给图片文件名加上表名和测试用例名，并记录一个简单的 hash。当 mock 数据没有变化时跳过生成，避免大量无意义的文件变更。不过要注意，ScyllaDB 的 uuid 字段如果使用随机值，快照会每次都不同，这时应当把随机字段替换为固定值再做比较。

此外，还可以在图片底部添加元信息，比如生成时间、数据行数、主键名称和驱动版本。这些信息能帮助后续排查问题，特别是当测试失败原因是数据不一致时，一张带上下文的快照比纯文本日志更有说服力。

五、常见问题与性能优化

生成大表图片时，字符串拼接可能成为瓶颈。如果行数超过 500，建议分批计算列宽，避免一次性遍历所有行导致内存峰值过高。也可以使用 stream 的方式把 SVG 分块写入文件，而不是先拼出完整字符串。对于日常 mock 测试，通常在 100 行以内，性能差异不大。

另一个容易忽略的点是字体。SVG 文本默认依赖系统字体，如果 CI 运行在精简容器里，中文可能会显示成方块。可以在构建阶段安装 Noto Sans CJK 字体，或者在 SVG 中指定通用字体族，如 font-family="Arial, sans-serif"。如果必须支持中文字符，建议提前测试目标环境的字体配置。

最后，如果团队已经使用 Cassandra 或 ScyllaDB 的官方测试容器，也可以把 Mock2Image 接到真实测试容器的查询结果上。这样既保留了真实行为，又能得到可视化的数据快照，比纯 mock 更接近生产问题。

Node.jsScyllaDBMock2Image修改时间：2026-09-28 10:06:32