从DSL到布局引擎：代码化架构图工具的设计与实现

diagram-design 是我最近大半年在打磨的一个个人项目。简单说，它是一套用写代码的方式来画架构图、流程图、时序图的完整方案：你用一段结构化的文本描述节点和连线，工具负责自动排版、自动渲染成标准 SVG，还能直接嵌入文档、PPT、甚至 CI 流程里。做这个项目的直接动机，是团队里长期存在的“架构图与线上真实架构不一致”问题——传统拖拽式画图工具画完就扔，版本管理靠截图保存，评审时对不上号，迭代两轮之后图基本就废了。这篇文章会完整拆解这个项目从需求分析、DSL 设计、解析器实现、布局引擎到渲染输出的全过程，把每个环节的关键决策和踩过的坑都记录下来。如果你也在做类似的方向，或者正在为团队的文档治理头疼，这篇文章应该能给你不少可复用的思路。

1. 项目定位与整体设计思路

1.1 传统画图方式的痛点和这个项目要解决的事

我先说一个很真实的场景：今年年初我们做一次系统重构评审，架构师在会议上打开了一张 Visio 画的系统拓扑图，图上还有三个服务是去年就已经下线了的。全场没人注意到，直到负责运维的同事指着其中一个节点说“这个服务现在已经拆掉了”，场面一度非常尴尬。

这不是个例。传统拖拽式画图工具的普遍问题是：

• 图的存在形式是二进制文件或私有格式，Git 没法做有意义的 diff，代码评审基本靠肉眼。
• 节点位置是手动拖出来的，谁拖谁负责，一旦团队成员变动，图的维护就断档。
• 图里的信息和真实代码、配置、部署清单没有建立关联，全靠人工同步，过期是常态而非例外。
• 多人协作习惯不同，有人喜欢用 Visio，有人喜欢 ProcessOn，有人直接画在白板上拍照发群里，最后文档里堆了一堆格式各异的图。

做 diagram-design 的时候，我把目标定得很朴素：让画图变成写代码，让图能进 Git，让图能自动更新，让人不用再记节点坐标。

这个定位意味着几个关键选型：图的描述必须用纯文本格式，格式必须简单到让人愿意写，渲染必须自动化到不需要人工干预。我花了很长时间在各种现有方案之间犹豫，最后决定自己写一个轻量级的 DSL，这个选择的过程值得单独拿出来讲一讲。

1.2 为什么没直接选 Mermaid，而要自己写一套 DSL

在选择技术路线的时候，我对比了当下比较主流的几个方案。

Mermaid 是很多人的第一反应，它优点很明显：语法简单，JavaScript 生态，支持流程图、时序图、甘特图等多种类型，GitHub 原生支持渲染。我对它也最熟悉，Team 里已经有不少人用它画时序图。但是我有几个绕不过去的痛点。

PlantUML 也是老牌方案，Java 写的，语法有自己的风格，时序图支持得非常好。但部署依赖 Java 环境，输出风格的定制能力比较弱，对中文字体的处理有时候需要额外配置。

Graphviz 则完全是另一条路线，它核心是 dot 语言的布局引擎，定位是图自动布局，它的算法能力极强，很多专业工具底层都是它。但它的语法太底层了，描述一个简单的业务流程都要写一大堆属性。

Mermaid 最大的问题，在我的使用场景里，是它为了保证内置的渲染能力，做了一个相对“重”的语法体系，不同图类型的关键字差异较大——类图的关键字和时序图的关键字完全是两套体系，学习成本比我预想的高。同时它把布局逻辑和渲染高度耦合，我想做定制化的布局策略时非常吃力。

我给自己列了一张对比表：

方案	学习成本	定制能力	布局效果	部署依赖	适合我的程度
Mermaid	较低	中等	一般	无	一般
PlantUML	中等	中等偏弱	一般	需要 Java	一般
Graphviz	高	强	强	本地库	中等
自研 DSL	前期高	完全可控	按需实现	无	高

看完这张表你就会发现，我选自研其实不是因为它完美，而是因为我在这个项目上真正想要的两个能力，现成方案都给不了：第一，我想让图表的 DSL 和我团队后端服务定义的接口结构做一个深度关联，让图可以“半自动生成”；第二，我想要一个完全可控的渲染输出，包括主题、布局方向和交互事件，这些在 Mermaid 里想实现得绕很多弯路。

当然，自研的代价也很现实：所有解析、布局、渲染都得自己从零开始搭。我的应对思路是：把范围收窄。我不做甘特图，不做饼图，不追求大而全，只做架构图、流程图、时序图这三类，并且把这三类做到足够好用。这就是 diagram-design 的核心边界。

1.3 项目整体架构与数据流设计

整个项目分成了五个核心模块，每个模块只做一件事，模块之间通过明确的数据结构衔接。

第一个模块是 DSL 解析层，负责把用户写的文本解析成内存里的 AST（抽象语法树）。第二个模块是语义校验层，负责检查节点 ID 是否重复、连线引用的节点是否存在、有没有循环依赖之类的问题。第三个模块是布局引擎，负责计算每个节点的坐标位置和每条连线的路由路径。第四个模块是渲染层，把已经带坐标的图数据渲染成 SVG 或者 PNG。第五个模块是导出与集成层，负责处理导出文档嵌入、样式表注入、交互事件绑定这些外围需求。

数据流是这样走的：

DSL 文本 -> 词法分析 -> 语法分析 -> AST -> 语义校验 -> 校验后的图模型 -> 布局引擎 -> 带坐标的图模型 -> 渲染层 -> SVG / PNG

这里最关键的设计决策是：布局引擎和渲染层严格解耦。布局引擎完全不知道 SVG 是什么，它就是纯数学的坐标计算，输入是图结构和节点尺寸，输出是节点位置和连线路径。渲染层完全不知道布局算法怎么算的，它只负责把带坐标的图模型画出来。

这样拆的好处非常明显：以后我想加 Canvas 渲染，直接新写一个渲染器就可以；想换一套布局算法，也不影响渲染。实际开发中，我把测试也按这个边界拆开，布局引擎的测试全跑纯函数，不用起浏览器，速度快得飞起。

2. 核心技术细节解析与实操要点

2.1 我的 DSL 语法是怎么设计的

DSL 设计是这类项目的灵魂，也是最容易返工的地方。我当时给自己定了三条硬性规则。

第一条规则是：语法必须能覆盖 90% 的常见图，但关键字数量要控制在 10 个以内。太多关键字用户记不住，太少又表达不了复杂结构。

第二条规则是：所有结构都必须有明确的“块”边界。节点怎么开始、怎么结束要一眼能看出来，连线和节点不能混淆。

第三条规则是：注释必须原生支持，而且要支持行注释和块注释两种。没有注释的 DSL 在生产环境里就是个灾难。

我最终定下来的语法骨架是这样的：

graph 用户中心 { # 这是注释：定义一个服务节点 服务网关 = { type: 服务 } 用户服务 = { type: 服务 } 数据库 = { type: 存储 } 服务网关 -> 用户服务 = { label: 转发请求 线型: 实线 } 用户服务 -> 数据库 = { label: 读写用户数据 线型: 实线 } }

整体语法结构就是：先声明图类型，然后一个大括号块里写节点定义和连线定义。节点定义是“变量名 = { 属性块 }”，连线定义是“源 -> 目标 = { 属性块 }”。

语法确定后，我加了一条自己的心得：节点的 ID 必须支持字母、数字、下划线，但不要支持空格和中划线。一开始我觉得中划线没问题，结果在做代码生成的时候，中划线在部分语言里会被解释成减号，导致自动生成的代码跑不过编译。真人头这一行，实际开发里坑了我整整一下午，后来直接写进语法规范里禁掉了。

2.2 解析器的实现：用递归下降还是用解析器生成器

解析器的技术路线选择上，我考虑过两条路：用 PEG.js 这类解析器生成器，还是手写递归下降解析器。

先说说 PEG.js 方案的优缺点。优点是快，语法文件一写，解析器代码自动生成，不用自己手撸状态机。缺点是调试起来黑盒，生成的代码可读性差，遇到模棱两可的语法错误信息很让人头大。当时我想，DSL 本身的语法规则并不多，不到十个关键字，手写递归下降解析器的工作量完全可接受。

事实证明这个决定是对的。手写递归下降解析器的调试体验好太多了，出现语法错误时我可以精确抛出行号和列的提示，用户能直接定位到错误位置。这是我在实际项目里特别在意的一点：解析器的报错信息质量，决定了这个 DSL 好不好用。

核心解析逻辑分两层：

第一层是词法分析，把字符串切成 token 流。我定义的 token 类型就四种：标识符（节点名、属性名）、字符串（属性值）、符号（大括号、箭头、等号、逗号）、注释。整个词法分析器不到 150 行，简单到不写状态机就能处理。

第二层是语法分析，按递归下降的方式处理 token 流。一个函数处理一个语法结构，比如 parseGraph 处理图块，parseNode 处理节点定义，parseLink 处理连线定义。

具体实现里有个容易翻车的地方值得分享：属性块的解析。属性值的类型不固定，可能是字符串也可能是数字，比如“宽: 300”和“label: 用户服务”。我的做法是统一走字符串解析，然后在语义层面做类型转换和校验。这个设计让语法层非常薄，把复杂逻辑都下沉到语义层，整体代码结构清爽很多。

2.3 语义校验：让用户第一时间发现错误

解析成 AST 之后，真正有意义的是语义校验。这块有四个必做项。

第一项是节点 ID 唯一性检查。重复节点 ID 会导致渲染结果不可预知，这个必须直接报错。

第二项是连线端点检查。每一条连线的源节点和目标节点必须都存在于图中，不存在就直接报错。这个看似简单，实际使用中能拦下大量低级错误。

第三项是类型检查。比如节点定义里写了“type: 数据库”，属性值“数据库”不在声明的枚举值列表里，要给出友好提示。

第四项是循环依赖检查。对于层级图布局，如果图里出现环，布局算法会陷入死循环或者输出错乱。我之前吃的亏就是没做这项，导致渲染一个环形依赖的架构图时布局直接乱掉了。

这里分享一个很关键的工程实践：语义校验错误列表要一次性收集，而不是遇到第一个错就返回。我之前是发现错误直接 throw，结果用户能看到一次只有一个错误，改完再跑又暴露下一个，体验很糟糕。后来改成收集模式，一次性把所有问题列出来，用户一次改完，效率高多了。

2.4 布局引擎：从零实现一个够用的层级布局

布局引擎是这个项目里数学含量最高的部分，也是我花时间最多的地方。我的需求很明确：多数架构图、流程图是自上而下或者从左到右的层级结构，我要的是一个能处理有向无环图的“层级布局”算法。

Level-based layout 的思路说起来不复杂，分四步。

第一步，拓扑排序。把所有节点按依赖顺序分层，没有入边的节点放第一层，只依赖第一层节点的放第二层，依此类推。

第二步，层内排序。每一层的节点尽量按它们在图中的出现顺序排，减少连线交叉的可能。交叉减少这一步我用了经典的 barycenter 启发式算法，它不是最完美的解，但对 95% 的图来说效果足够好。

第三步，分配坐标。层与层之间按固定垂直间距排，层内节点按固定水平间距排。到了这一步，每个节点的 x 和 y 都有初始值了。

第四步，连线路由计算。对于跨层的边，我要生成一条从源节点底部到目标节点顶部的折线路径。路径由多个控制点组成，中间经过的每一层都要留出位置。

有个参数选择值得细说：层间距和同层节点间距的默认值。我最初凭感觉设定了 80 和 40，结果渲染出来的图很挤。后来我从实际输出的图里统计了一下节点的平均尺寸，再结合 16:10 的屏幕比例，反推出间距参数：层间距设为节点平均高度的 1.8 倍，同层间距设为节点平均宽度的 0.6 倍，视觉上最舒服。

这里补充一个布局引擎的实现要点：一定不要用递归实现拓扑排序，数据量稍大的图会爆栈。我用的 Kahn 算法，配合一个入度数组和队列，非常稳。

2.5 渲染层：为什么输出 SVG 而不是 Canvas

渲染方案对比了很久，SVG vs Canvas，我毫不犹豫选了 SVG。原因是：架构图和流程图是“信息密集但交互少”的图，SVG 的 DOM 结构天然适合做事件绑定和元素级样式控制，缩放不模糊，还能直接用 CSS 定制主题。Canvas 的性能更好，但它是像素级的，没法做到单个节点被点击时的事件响应，对于文档场景来说没必要。

SVG 渲染层内部，我做了比较细的模块拆分：

• 画布初始化模块：设置 viewBox、背景色、缩放级别。
• 节点渲染模块：不同 type 对应不同的视觉样式——服务节点用圆角矩形，存储节点用圆柱，外部依赖用带阴影的矩形。
• 连线渲染模块：处理折线的拐角方向和箭头。
• 文本渲染模块：处理节点内文本溢出、换行和字体居中。
• 主题模块：从外部 JSON 里读颜色、字体、边框粗细。

细节决定成败。比如文本居中，SVG 里的 text 元素默认锚点在文本左下角，要做垂直居中需要手动计算 font-size 和行高，我在这个细节上踩过坑，后来写了一个基于给定字体和字号测量文本真实尺寸的工具函数，才算彻底解决。

2.6 导出功能设计：从 SVG 到 PNG 要做到像素级还原

导出 PNG 的需求很自然——SVG 不是所有场景都通用，很多人还是想要一张可以放进 PPT 里的图片。

要实现高质量导出，我记得最先想到的思路是直接把 SVG 塞进 canvas 然后转 PNG，结果发现很多坑：SVG 里的外部字体加载不完全、非标准属性被忽略、背景色透明导致截图发灰。后来我改为增加一个导出专用的渲染器，基于同样的图数据模型，用 canvas 重新绘制，字体统一用系统字体栈，背景色单独处理，这样反而更好控制了。

导出时还有一个体验细节：PNG 的缩放倍率。我的做法是默认导出两倍图，即 scale 参数为 2，保证放到 PPT 和 Retina 屏幕上不模糊。这个参数我开放出来了，用户如果需要三倍图可以自己配。

3. 实操实现：一个可复现的最小闭环

这一节我直接把项目怎么跑起来、代码是怎么组织的写清楚。如果你也想搭一个类似的画图工具，按这个流程走可以少踩很多坑。

3.1 工程初始化与依赖选型

技术栈我选了 TypeScript + Node.js，没有用前端框架。原因有二：第一，核心逻辑跟 UI 无关，CLI 工具用 Node 就跑，不用起浏览器；第二，TypeScript 的静态类型对 AST 这类复杂数据结构的开发体验非常友好，重构时编译器能帮你兜底。

工程结构如下：

diagram-design/ ├── src/ │ ├── parser/ │ │ ├── lexer.ts │ │ ├── parser.ts │ │ └── ast.ts │ ├── semantic/ │ │ ├── validator.ts │ │ └── model.ts │ ├── layout/ │ │ ├── levelLayout.ts │ │ └── edgeRouter.ts │ ├── render/ │ │ ├── svgRenderer.ts │ │ └── canvasRenderer.ts │ ├── export/ │ │ ├── png.ts │ │ └── index.ts │ └── cli.ts ├── test/ ├── templates/ └── package.json

package.json 里核心依赖就三个：commander 做 CLI 参数解析，yaml 做自定义主题的格式选择，sharp 或者纯 canvas 做 PNG 导出。其他几十个都是工具链依赖，对业务逻辑没有影响。

3.2 词法分析器核心代码实现

词法分析器把输入字符串切成 token。这个片段完全体现了我前面说的“极简风格”：

export type TokenType = "IDENT" | "STRING" | "SYMBOL" | "COMMENT"; export interface Token { type: TokenType; value: string; line: number; col: number; } export function tokenize(input: string): Token[] { const tokens: Token[] = []; let i = 0; let line = 1; let col = 1; const isIdentStart = (c: string) => /[A-Za-z_\u4e00-\u9fa5]/.test(c); const isIdentPart = (c: string) => /[A-Za-z0-9_\u4e00-\u9fa5]/.test(c); while (i < input.length) { const ch = input[i]; if (ch === "\n") { line++; col = 1; i++; continue; } if (ch === " " || ch === "\t") { i++; col++; continue; } if (ch === "#") { while (i < input.length && input[i] !== "\n") { i++; col++; } tokens.push({ type: "COMMENT", value: "", line, col }); continue; } if (isIdentStart(ch)) { const start = i; while (i < input.length && isIdentPart(input[i])) { i++; col++; } tokens.push({ type: "IDENT", value: input.slice(start, i), line, col }); continue; } if (ch === "\"") { const startLine = line; const startCol = col; i++; col++; let value = ""; while (i < input.length && input[i] !== "\"") { value += input[i]; i++; col++; } if (input[i] === "\"") { i++; col++; } tokens.push({ type: "STRING", value, line: startLine, col: startCol }); continue; } if (["{", "}", "=", "-", ">", ",", ":"].includes(ch)) { let symbol = ch; if (ch === "-" && input[i + 1] === ">") { symbol = "->"; i += 2; col += 2; } else { i++; col++; } tokens.push({ type: "SYMBOL", value: symbol, line, col }); continue; } throw new Error(`Unexpected char "${ch}" at ${line}:${col}`); } return tokens; }

这个小函数有两个设计亮点。第一个是支持 UTF-8 中文标识符，我测试下来团队里不少人喜欢用中文写节点名，这个支持是刚需。第二个是注释直接吞掉，不参与语法分析，所以注释里写什么都不会影响解析正确性。

3.3 语法分析器实现：递归下降的思路

用递归下降解析 token 流，我按语法结构拆了四个解析函数。这是一个极简但核心的片段：

export function parse(tokens: Token[]): Graph { let pos = 0; const expect = (value: string) => { const token = tokens[pos]; if (!token || token.value !== value) { throw new Error(`Expect "${value}" but got "${token?.value}" at line ${token?.line}`); } pos++; }; const expectIdent = () => { const token = tokens[pos]; if (!token || token.type !== "IDENT") { throw new Error(`Expect identifier but got "${token?.value}" at line ${token?.line}`); } pos++; return token.value; }; function parseNode(): Node { const id = expectIdent(); expect("{"); const props: Record<string, string> = {}; while (tokens[pos] && tokens[pos].value !== "}") { const key = expectIdent(); expect(":"); const value = tokens[pos]; if (value.type !== "STRING" && value.type !== "IDENT") { throw new Error("Expect property value"); } props[key] = value.value; pos++; } expect("}"); return { id, type: "node", props }; } function parseLink(): Link { const source = expectIdent(); expect("->"); const target = expectIdent(); expect("{"); const props: Record<string, string> = {}; while (tokens[pos] && tokens[pos].value !== "}") { const key = expectIdent(); expect(":"); const value = tokens[pos]; props[key] = value.value; pos++; } expect("}"); return { source, target, type: "link", props }; } expectIdent(); // graph expectIdent(); // 图名 expect("{"); const nodes: Node[] = []; const links: Link[] = []; while (tokens[pos] && tokens[pos].value !== "}") { const startPos = pos; // 尝试解析节点，如果失败则回退并解析连线 try { const savedPos = pos; const maybeNode = parseNode(); nodes.push(maybeNode); } catch (e) { pos = startPos; const link = parseLink(); links.push(link); } } return { nodes, links }; }

这段代码体现了一个非常实用的容错技巧：先用尝试解析方式处理节点，失败就回退再按连线解析。这样写虽然性能不如精确预测分支，但维护成本极低，加了新语法结构时不需要改其他分支。

3.4 布局计算的参数配置与实现效果

布局的参数我全部集中在配置对象里，方便用户覆盖：

{ "layout": { "direction": "TB", "levelSpacing": 80, "nodeSpacing": 40, "margin": 50 } }

direction 决定方向，TB 是自上而下，LR 是自左向右。levelSpacing 是层间距，nodeSpacing 是同层节点间距，margin 是画布边缘空白。

布局算法核心是三层循环：第一层按层处理节点，第二层处理层内排序，第三层计算实际坐标。间距调整我封装成一个纯函数：

export function computeNodePositions(nodes: Node[], levels: number[][], config: LayoutConfig): Map<string, Point> { const positions = new Map<string, Point>(); const nodeHeight = 60; const nodeWidth = 180; levels.forEach((levelNodes, levelIndex) => { levelNodes.forEach((nodeId, nodeIndex) => { const x = config.margin + nodeIndex * (nodeWidth + config.nodeSpacing); const y = config.margin + levelIndex * (nodeHeight + config.levelSpacing); positions.set(nodeId, { x, y }); }); }); return positions; }

实际运行效果是：输入一段二十个节点、三十条连线的架构描述，从解析到布局计算完成，耗时没有超过 50ms，输出坐标直接灌给渲染层就能出图。这个性能对绝大多数场景绰绰有余。

3.5 渲染层的 SVG 生成模板

渲染层我基于图模型拼 SVG 字符串。核心思路是：不搞复杂的虚拟 DOM，直接做字符串模板拼接。代码量少，可读性好，性能也高。

export function renderSVG(model: DiagramModel): string { const nodes = model.nodes.map((n) => { return `<g class="node node-${n.props.type}" transform="translate(${n.x}, ${n.y})"> <rect width="${n.width}" height="${n.height}" rx="8" ry="8"/> <text x="${n.width / 2}" y="${n.height / 2 + 6}" text-anchor="middle">${escapeXml(n.id)}</text> </g>`; }).join("\n"); const links = model.links.map((l) => { const path = buildPath(l.points); return `<g class="link"><path d="${path}" fill="none" stroke="#888" stroke-width="2"/></g>`; }).join("\n"); return `<svg xmlns="http://www.w3.org/2000/svg" width="${model.width}" height="${model.height}">${nodes}${links}</svg>`; }

escapeXml 函数必须写，不然节点名里带了<或&会让整个 SVG 挂掉。这个细节我在测试时被一个使用中文引号的节点名坑过一次，后来全局搜了一遍所有渲染路径才补全。

3.6 导出 PNG 的像素级还原细节

导出 PNG 我用的方案是 Node Canvas。因为这个库和系统图形库绑定，安装时偶尔会踩环境坑，我建议在 Docker 里构建好环境，不然换个电脑就要折腾半天。

关键步骤如下：

1. 先把 SVG 的逻辑尺寸和 viewBox 做映射。
2. 根据导出倍率 scale 创建同比例的 Canvas。
3. 用 Canvas 重新绘制所有节点和连线。
4. 对文本设置统一的字体栈。
5. 设置背景色：如果没有指定，默认白色，不透明。
6. 转成 PNG buffer，写入文件。

导出 PNG 里有个很容易忽略的点：字体。SVG 里可以引用系统字体，导出到 Canvas 时如果字体没加载好，文字就会变成方框。我的解法是只依赖字体栈system-ui, "PingFang SC", "Microsoft YaHei", sans-serif，不用任何自定义字体，保证跨平台稳定。

4. 常见问题与排查技巧实录

4.1 布局重叠：节点叠在一起怎么办

布局重叠是我遇到最多的反馈。总结下来原因有三个：

一是节点尺寸和布局默认参数不匹配。如果一个节点内部的文本太长，渲染出来的实际尺寸比布局引擎预设的 180 x 60 大，就会和相邻节点重叠。解决思路是布局之前先统一预估所有节点的实际尺寸，让布局引擎基于“真实尺寸”而非“默认尺寸”来计算。

二是同层节点数差异过大。某一层只有一个节点，另一层有八个节点，前者宽度分配不合理，导致连线在中间层交叉重叠。这个问题的解决办法是给每个节点增加一个“占位宽度”的概念，最少占位为节点自身尺寸，最大占位可根据同层节点数量动态分配。

三是用户手动指定了节点大小和位置。这种情况我会直接提示：如果手动指定过坐标，布局引擎只处理未指定的节点，混排模式下重叠概率会上升。

4.2 循环依赖导致布局崩溃

我在语义校验里做了循环依赖检测，但还是有用户用其他工具手动改了图结构，绕过校验，结果布局阶段直接卡死。

排查思路很简单：给布局引擎加一个最大迭代次数限制。一旦超过三千次，主动报错并提示“存在循环依赖，请检查图结构”。这个兜底逻辑加上之后，再也没有出现过挂死情况。

4.3 中文字体导出 PNG 发虚

这个问题折磨了我一阵。SVG 里中文渲染得好好的，导出成 PNG 后文字边缘发虚、发糊。

后来排查到原因：Node Canvas 在 Linux 环境下面没有内置中文字体，需要手动安装字体包，或者在代码里显式注册字体文件路径。我在项目里默认加载了一个开源中文字体文件，并且在 README 里注明“如果系统未安装中文字体，请执行字体安装脚本”，这个问题就从根上解决了。

4.4 大型图的性能优化

当节点数超过五百个、连线超过一千条时，纯 SVG 渲染会开始卡顿。我的优化策略分三档：

第一档是布局阶段优化。把 O(n^2) 层的排序逻辑改成按层分批处理，避免全局嵌套循环。

第二档是渲染优化。对 SVG 的节点做简单的元素合并，同一层的节点打包进一个<g>，减少 DOM 节点数量。

第三档是交互优化。默认不渲染“非可视区域”的连线，只在需要时懒加载。

实测五百节点下，纯渲染用时从一档的 400ms 降到三档的 90ms 左右，体感流畅很多。

5. 工程化落地：让架构图不再是“一次性文档”

5.1 接入 CLI 和 CI 流程

光有核心库还不够，能落地才是有价值的。我给 diagram-design 做了一个命令行工具，用法如下：

diagram-design -i ./docs/architecture.dd -o ./dist/architecture.svg --theme dark

这样每次仓库代码更新，CI 流程里跑一次命令，最新的架构图就会自动生成，并提交到文档目录。这相当于把“架构图和代码同步过期”的问题彻底废掉了——图不再是人工维护的资料，而是从代码仓库里“长出来”的产物。

CI 接入过程里我遇到过一个小坑：GitHub Actions 的 Runner 环境没装中文字体，生成的 SVG 在预览时中文显示正常，一旦导出 PNG 就全是方框。最终解决方案是在 CI 的 yml 里加一句apt-get install fonts-noto-cjk，问题彻底解决。

5.2 从画图工具到文档基建的一部分

做到这一步，它已经不仅仅是一个画图工具了，而是在搭建团队文档基建的一部分。

现在我往团队内部推的时候，重点讲三个使用场景：技术方案设计阶段，用图来描述目标架构和现状差异；代码评审阶段，用图辅助说明模块间的数据流和依赖关系；服务治理阶段，把真实的服务依赖数据自动化生成图，当作监控面板的辅助视图。

这个方向的扩展空间很大。下一步我打算做的方向是：解析 Kubernetes Deployment Yaml 里的 service 和 deployment 关系，直接自动生成服务架构图；解析后端代码里的路由注册，自动生成 API 时序图。等到这两个能力落地，图就真的和线上系统同步了。

最后再说回这个项目本身。diagram-design 不是一个多复杂的技术项目，它的核心价值是想清楚了一个很多人忽略的问题：画图的价值不在于“画”的动作，而在于图能否持续保持真实。传统的画图工具把重心放在“画”上，我的方案把重心放在“保持真实”上。做这个项目的过程中，我学到的最重要一课是：工具设计的边界比功能更重要。我一开始也想做支持所有图类型的全能选手，后来发现把范围收窄，反而能把每一类图做得更深入。这个思路，放到任何技术项目里都值得借鉴。