1. 从一张草图到一套系统：diagram-design 到底在解决什么问题
第一次看到 “diagram-design” 这个标题，很多人会以为它只是一个画图工具的别名，或者某个设计稿模板库。但真正做过系统设计、技术方案评审、跨团队协作的人会立刻意识到，这个标题背后藏着一个非常具体且高频的痛点：如何把脑子里零散的结构、流程、关系，快速变成一张别人能看懂、自己能维护、团队能复用的图。
我最早接触这类需求是在一次跨部门方案评审上。当时需要把一套数据流转逻辑讲清楚，我花了两个小时用传统绘图工具画了一张图，结果会上被问了三个问题：这个节点为什么在这里、那条线为什么绕了一圈、如果中间某个环节失败会怎样。图是画出来了，但信息密度极低，修改成本极高，而且换一个人来维护几乎等于重画。那次之后我开始意识到，画图不是美术问题，是信息架构问题。diagram-design 这个项目标题，本质上指向的就是一套“用工程化思维做图”的方法论和工具链。
它适合谁？如果你符合下面任意一条，这个内容就值得你花时间：
- 经常需要画架构图、流程图、时序图、状态图，但每次都觉得“画完就过时”；
- 团队里每个人画图风格不一样，图与图之间无法拼接，评审时沟通成本极高；
- 想用代码或结构化文本生成图，但又不想学太重的 DSL；
- 做技术文档、方案汇报、教学材料，需要图能跟着内容一起版本管理。
我个人的判断是，diagram-design 的核心价值不在于“画得好看”，而在于把图从一次性消费品变成可维护资产。下面我会从整体设计思路、核心细节、实操过程、常见问题四个层面，把这套东西拆开讲透。你不需要有设计背景，只要会写结构化文本、理解基本的层级关系，就能跟着做。
2. 整体设计与思路拆解：为什么不是“打开画布就画”
2.1 先定信息层级，再定视觉样式
绝大多数人画图的第一步是打开工具、拖一个框、写几个字。diagram-design 的思路完全相反：先确定这张图要回答什么问题，再决定用什么结构，最后才考虑颜色和线条。这个顺序听起来简单，但实际执行时能过滤掉大量无效工作。
我习惯把图分成三类：
| 图类型 | 核心回答的问题 | 推荐结构 | 典型场景 |
|---|---|---|---|
| 架构图 | 系统由哪些部分组成，边界在哪 | 分层 + 分组 | 技术方案评审 |
| 流程图 | 一件事按什么顺序发生 | 线性 + 分支 | 业务流程梳理 |
| 关系图 | 谁依赖谁，谁影响谁 | 节点 + 连线 | 数据血缘、组织协作 |
这个分类的意义在于：不同类型的图，信息密度和修改频率完全不同。架构图通常一个季度才大改一次，流程图可能每周都在变，关系图则经常需要动态生成。如果你用画架构图的方式去维护流程图，每次改动都会很痛苦；反过来，用流程图的线性思维去画架构图，又会丢失层级和边界信息。
diagram-design 的第一个设计决策就是：把“结构定义”和“视觉呈现”分离。结构定义用纯文本或结构化数据描述，视觉呈现交给渲染引擎。这样做的好处是，改结构不需要动样式，换样式不需要重画结构。我试过在一个中型项目里用这种方式维护二十多张图，季度评审时只改了结构定义文件，所有图的布局自动重排，节省的时间至少是传统方式的五倍。
2.2 为什么选择“文本驱动”而不是“拖拽驱动”
拖拽式工具的优势是上手快，劣势是不可版本化、不可批量修改、不可程序化生成。diagram-design 选择文本驱动，核心考量有三个：
第一，版本管理。文本可以进 Git，每次改动都有记录，谁在什么时候改了哪个节点一目了然。拖拽式工具生成的二进制文件，diff 出来全是乱码，评审时根本没法看。
第二，复用与组合。文本定义可以拆成片段，不同图之间共享公共部分。比如多个架构图都包含“用户认证”模块，抽成一个片段后，改一处所有图同步更新。拖拽式工具要做到这一点，要么复制粘贴，要么手动同步，维护成本随图数量线性增长。
第三，程序化生成。当系统规模大到一定程度，图不可能手动画。比如微服务依赖关系，服务数量上百个，手动维护不现实。文本驱动意味着你可以写脚本从配置中心、服务注册表、代码注释里提取关系，自动生成图定义。这是拖拽式工具完全做不到的。
注意：文本驱动不是让你手写所有东西。初期可以手写核心结构，后期逐步引入脚本生成。关键是保持“结构可读、可改、可追溯”。
2.3 布局引擎的选择逻辑：为什么不是自己算坐标
很多人第一次尝试文本驱动画图时，会想自己计算每个节点的 x、y 坐标。我强烈建议不要这么做。原因很简单：布局是一个约束满足问题，手动算坐标等于把自己变成布局引擎，而且是最笨的那种。
diagram-design 的合理做法是：结构定义只描述“谁连谁、谁属于谁”，坐标交给布局引擎。常见的布局算法有：
- 分层布局：适合有向无环图，节点按依赖关系分层，箭头统一方向。架构图、流程图首选。
- 力导向布局：适合关系复杂的网络图，节点之间相互排斥、连线像弹簧。关系图、拓扑图常用。
- 树形布局：适合层级严格的结构，比如组织架构、分类目录。
- 序列布局：适合时序图，按时间轴排列参与者。
选择布局引擎时，重点看三个指标：是否支持增量布局（改一个节点不用全图重排）、是否支持约束（比如某些节点必须同层、某些边不能交叉）、输出格式是否可定制（SVG、PNG、PDF）。我实测下来，分层布局在大多数技术场景下最稳，力导向布局好看但每次渲染结果可能不同，不适合需要稳定输出的文档。
2.4 视觉规范的最小集：颜色、字体、间距
diagram-design 不追求花哨的视觉效果，但有一套最小视觉规范。我的经验是，颜色不超过四种，字体不超过两种，间距用固定倍数。
颜色方面：一种主色用于核心节点，一种辅助色用于外部依赖，一种警示色用于风险点，一种中性色用于背景和连线。超过四种颜色，读者注意力会被分散，反而记不住重点。
字体方面：标题和正文各一种。标题用无衬线字体，正文用等宽或易读字体。字号至少三档：图标题、节点标题、节点说明。字号差距要明显，否则层级出不来。
间距方面：节点内边距、节点间距、分组间距，全部用同一个基数的倍数。比如基数 8px，内边距 16px，节点间距 24px，分组间距 40px。这样整张图看起来会有节奏感，不会忽松忽紧。
提示：视觉规范一旦定下来，就写进项目说明里，所有人遵守。图与图之间风格统一，拼接时不会有割裂感。
3. 核心细节解析与实操要点：从定义到渲染的完整链路
3.1 结构定义的三种写法与适用场景
diagram-design 的结构定义可以用多种形式表达，我常用的有三种：
第一种：缩进式文本。用缩进表示层级，用箭头表示关系。适合快速起草，可读性最好。
系统A 模块A1 依赖 -> 模块B1 模块A2 依赖 -> 模块B2 系统B 模块B1 模块B2第二种：结构化数据。用 JSON 或 YAML 描述节点和边。适合程序生成，字段明确。
nodes: - id: a1 label: 模块A1 group: 系统A - id: b1 label: 模块B1 group: 系统B edges: - from: a1 to: b1 label: 依赖第三种：领域特定语法。类似 PlantUML 或 Mermaid 的写法，用关键字描述图类型和元素。适合熟悉 DSL 的团队。
graph LR A[模块A1] --> B[模块B1] A --> C[模块B2]三种写法没有绝对优劣，关键看谁来维护。如果维护者是开发者，结构化数据最顺手；如果维护者是产品经理，缩进式文本更友好；如果团队已经有 DSL 使用习惯，直接沿用即可。我个人的做法是：核心架构图用结构化数据，临时讨论图用缩进式文本，对外文档用 DSL 渲染成静态图。
3.2 节点与边的命名规范：让图自己说话
图看不懂，十有八九是命名出了问题。diagram-design 对命名有两条硬规则：
规则一：节点名必须是名词短语，不能是动词短语。比如“用户认证服务”可以，“认证用户”不行。因为节点代表一个实体或模块，不是动作。动作应该体现在边上。
规则二：边名必须是动词短语或状态描述。比如“调用”“依赖”“写入”“同步”。如果边没有名字，读者只能猜两个节点之间是什么关系，猜错概率极高。
我见过一张图，节点叫“处理订单”，边没有名字，读者完全不知道它是同步调用还是异步消息。后来改成节点“订单服务”，边“异步通知 -> 库存服务”，整个逻辑立刻清晰。
还有一个细节：节点名长度控制在 12 个字以内。超过 12 个字，节点框会变得很宽，布局引擎很难排得好看。如果信息确实多，拆成主标题和副标题，副标题用小字号。
3.3 分组与边界的表达技巧
架构图最怕的是“一锅粥”，所有节点平铺，看不出边界。diagram-design 用分组来解决这个问题。分组可以嵌套，但建议不超过三层。三层以上，读者会迷失。
分组的视觉表达有三种：
- 背景色块：最直观，但颜色多了会乱。建议只用浅灰或浅蓝。
- 虚线框：适合表示逻辑边界，不强调视觉重量。
- 标签括号：适合表示层级关系，比如“系统A”下面挂几个模块。
我通常组合使用：外层用背景色块表示系统边界，内层用虚线框表示模块边界，最内层用标签表示具体节点。这样从远到近，信息层级分明。
注意：分组边界不要和连线交叉太多。如果一条边必须穿过多个分组，考虑是否应该把分组拆开，或者把边改成经过某个中间节点。
3.4 布局参数的调优经验
布局引擎通常有一堆参数，但真正影响效果的只有几个：
| 参数 | 作用 | 推荐值 | 调整场景 |
|---|---|---|---|
| 节点间距 | 同层节点之间的距离 | 40-60px | 节点多时调小，节点少时调大 |
| 层间距 | 不同层之间的距离 | 80-120px | 边有标签时调大 |
| 边路由 | 连线走直线还是曲线 | 正交线 | 架构图用正交，关系图用曲线 |
| 对齐方式 | 节点左对齐还是居中 | 居中对齐 | 节点宽度差异大时用左对齐 |
我踩过的一个坑是：层间距太小，边标签和节点重叠。后来把层间距从 60px 调到 100px，标签立刻清晰了。另一个坑是：节点间距太大，图变得很散，读者视线移动距离过长。后来固定用 48px，配合分组，整体紧凑了很多。
3.5 输出格式的选择与后处理
diagram-design 的输出格式通常有 SVG、PNG、PDF 三种。我的选择逻辑是：
- SVG：首选。矢量格式，放大不糊，可以嵌入网页，可以用 CSS 调样式。缺点是某些老工具不支持。
- PNG：备用。位图格式，兼容性最好，适合插入文档和聊天工具。缺点是放大后模糊，需要导出高分辨率版本。
- PDF：打印和正式文档用。矢量格式，分页方便。
导出 SVG 后，我通常会做两件事：一是压缩冗余代码，去掉编辑器生成的元数据；二是给关键节点加 CSS 类名，方便在网页里做交互，比如鼠标悬停高亮。
提示：如果图要嵌入 Confluence 或类似文档平台，先导出 SVG，再转成平台支持的格式。直接粘贴 PNG 在 retina 屏幕上会模糊。
4. 实操过程与核心环节实现：从零搭一套可维护的图系统
4.1 环境准备与工具选型
假设你现在要从零开始，我建议的最小工具集是：
- 编辑器：VS Code，装一个 diagram 预览插件，边写边看。
- 版本管理：Git，图定义文件和代码一起提交。
- 渲染引擎：选一个支持文本定义、布局自动、输出 SVG 的引擎。具体选哪个看团队技术栈，关键是不要选需要手动调坐标的。
- 预览方式：本地起一个静态服务，或者用编辑器的实时预览功能。
安装步骤不复杂，核心是把渲染命令写进项目脚本。比如在 package.json 里加一行：
{ "scripts": { "diagram:build": "diagram-render --input docs/diagrams --output dist/diagrams" } }这样每次改完图定义，跑一条命令就能重新生成所有图。CI 里也可以加一步，确保图定义和代码同步更新。
4.2 第一个图的完整定义过程
我拿一个虚构的“订单处理系统”举例。第一步，列出所有节点：
- 用户端
- 订单服务
- 库存服务
- 支付服务
- 通知服务
- 数据库
第二步，确定分组：
- 前端层：用户端
- 服务层：订单服务、库存服务、支付服务、通知服务
- 存储层：数据库
第三步，确定边和方向：
- 用户端 -> 订单服务：创建订单
- 订单服务 -> 库存服务：锁定库存
- 订单服务 -> 支付服务：发起支付
- 支付服务 -> 订单服务：支付结果
- 订单服务 -> 通知服务：发送通知
- 订单服务 -> 数据库：写入订单
- 库存服务 -> 数据库：更新库存
第四步，写成结构化定义：
groups: - id: frontend label: 前端层 - id: services label: 服务层 - id: storage label: 存储层 nodes: - id: user label: 用户端 group: frontend - id: order label: 订单服务 group: services - id: inventory label: 库存服务 group: services - id: payment label: 支付服务 group: services - id: notify label: 通知服务 group: services - id: db label: 数据库 group: storage edges: - from: user to: order label: 创建订单 - from: order to: inventory label: 锁定库存 - from: order to: payment label: 发起支付 - from: payment to: order label: 支付结果 - from: order to: notify label: 发送通知 - from: order to: db label: 写入订单 - from: inventory to: db label: 更新库存第五步，渲染。跑一条命令，得到 SVG。检查布局是否合理，边标签是否重叠，分组是否清晰。如果不满意，调布局参数，重新渲染。
这个过程我走过很多遍，第一次通常要调三到五轮，后面熟悉了基本一轮过。关键是不要追求一次完美，先让图能看，再逐步优化。
4.3 参数计算：节点数量和布局复杂度的关系
布局引擎的复杂度大致是 O(n log n) 到 O(n²)，n 是节点数量。这意味着：
- 节点少于 20 个，布局几乎瞬间完成，随便调。
- 节点 20 到 50 个，布局需要几秒，建议减少不必要的边。
- 节点超过 50 个，布局可能变慢，而且图会变得很难看。这时候应该拆图，按子系统或按流程阶段拆成多张。
我实测过一个 80 节点的架构图，渲染出来密密麻麻，边交叉严重，根本没法看。后来拆成三张：核心服务图、数据流图、部署图，每张 20 到 30 个节点，清晰度立刻提升。
拆图的原则是：一张图只回答一个问题。如果一张图既要展示服务依赖，又要展示数据流向，还要展示部署拓扑，那它注定失败。
4.4 版本管理与协作流程
图定义文件进 Git 后，协作流程和代码一样：
- 新建分支，修改图定义。
- 本地渲染，检查效果。
- 提交 PR，附上渲染后的 SVG 截图。
- 评审人看 diff 和截图，提意见。
- 合并到主分支，CI 自动重新生成所有图。
这个流程的好处是：图的改动和代码的改动可以关联。比如某个服务重构了，PR 里既有代码改动，也有图定义改动，评审时能一起看，不会出现代码改了图没改的情况。
注意：图定义文件不要太大。单文件超过 500 行，考虑拆成多个文件，用引用组合。否则 diff 会很难看，评审效率低。
4.5 自动化生成：从代码到图的链路
当系统规模变大，手动维护图定义不现实。这时候需要自动化生成。常见的数据源有：
- 服务注册表：服务名、实例数、健康状态。
- 配置中心：服务依赖关系、超时配置。
- 代码注释：接口调用关系、数据流向。
- 数据库元数据：表结构、外键关系。
我做过一个实验：从服务注册表拉取服务列表，从配置中心拉取依赖关系，自动生成 YAML 定义，再渲染成图。整个过程脚本化，每次服务变更后自动更新图。虽然初期投入了两天时间写脚本，但后续维护成本几乎为零。
自动化生成的关键是数据质量。如果服务注册表里的依赖关系不全，生成的图就会缺边。所以自动化之前，先确保数据源可靠。
5. 常见问题与排查技巧实录：踩过的坑和填坑方法
5.1 图渲染出来一团糟，怎么快速定位问题
渲染结果不理想，通常有三个原因：节点太多、边太乱、分组不合理。我的排查顺序是：
- 数节点。超过 40 个，先拆图。
- 看边。有没有双向边、交叉边、无标签边。双向边改成两条单向边，交叉边考虑加中间节点，无标签边补标签。
- 查分组。分组是否嵌套过深，分组边界是否和边冲突。
我遇到过一次，图渲染出来所有节点挤在一起。查了半天发现是分组 id 重复了，两个不同分组用了同一个 id，布局引擎把它们当成一个组处理。改掉 id 后立刻正常。
5.2 边标签重叠的三种解法
边标签重叠是高频问题。解法按优先级：
- 调大层间距：最简单，但图会变高。
- 边标签加背景色：让标签浮在线上，但颜色要浅，否则抢眼。
- 改用正交路由：直线改折线，标签放在折线拐角处，重叠概率降低。
我通常先调层间距，不行再加背景色，最后才改路由。因为改路由可能影响整体布局，副作用较大。
5.3 布局引擎不支持的图类型怎么办
有些图类型，比如时序图、状态图，通用布局引擎支持不好。这时候有两个选择：
- 换专用引擎：时序图用序列布局引擎，状态图用状态机布局引擎。
- 降级表达：把时序图改成流程图，用节点表示步骤，用边表示时间顺序。
我倾向于换专用引擎，因为降级表达会丢失信息。比如时序图的激活框、返回箭头，流程图表达不了。但如果团队不想引入新工具，降级表达也是可接受的妥协。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 图渲染空白 | 定义文件语法错误 | 看渲染日志 | 检查缩进、括号、引号 |
| 节点重叠 | 布局参数太小 | 调大节点间距 | 增大间距或减少节点 |
| 边交叉严重 | 图结构太复杂 | 数边数量 | 拆图或加中间节点 |
| 分组不显示 | 分组 id 未引用 | 检查节点 group 字段 | 补上 group 引用 |
| 中文乱码 | 字体不支持 | 看渲染字体配置 | 指定支持中文的字体 |
| 导出 SVG 模糊 | 导出时缩放 | 检查导出参数 | 用矢量导出，不缩放 |
| 图更新后没变化 | 缓存未清除 | 看渲染时间戳 | 清缓存或加 --force |
| CI 里渲染失败 | 环境缺依赖 | 看 CI 日志 | 补依赖或固定版本 |
5.5 独家避坑技巧
技巧一：先画草图再写定义。不要一上来就写 YAML，先用纸笔或白板画出大概结构，确认逻辑没问题，再转成定义。这样能避免反复改定义。
技巧二：给节点加注释。YAML 支持注释，在节点旁边写一句说明，比如“这个服务已废弃，待下线”。过几个月回来看，能快速回忆起来。
技巧三：定期清理废弃节点。图定义和代码一样，会积累废弃内容。每个季度清理一次，删掉不再使用的节点和边，保持图精简。
技巧四：用颜色标记状态。比如绿色表示健康，黄色表示警告，红色表示故障。但颜色不要太多，三种足够。而且要在图例里说明，否则读者不知道颜色含义。
技巧五：导出时带时间戳。文件名加上日期，比如architecture-20250115.svg。这样能追溯历史版本，对比不同时期的架构变化。
6. 从单张图到图系统：规模化的扩展思路
6.1 图与文档的联动
图不是孤立的，它应该和文档联动。我的做法是：图定义文件旁边放一个 Markdown 文件，写清楚这张图的背景、关键决策、变更历史。渲染时，图嵌入文档，读者既能看图，又能看说明。
更进一步，可以用脚本从图定义里提取节点列表，自动生成文档的“模块说明”章节。这样改图定义，文档自动更新，不会出现图文档不一致的情况。
6.2 多图之间的引用与组合
当图数量多了，图与图之间会有引用关系。比如架构图里的某个模块，在详细设计图里展开。这时候可以用锚点引用：在架构图里给节点加一个链接，指向详细设计图。
实现方式取决于渲染引擎。有的支持在节点上加 URL，有的需要后处理 SVG 加超链接。我通常在后处理阶段用脚本给特定节点加<a>标签，实现点击跳转。
6.3 图的搜索与索引
图多了之后，找图是个问题。我的做法是：给每张图加元数据，比如标签、负责人、最后更新时间。然后用一个简单的索引文件汇总，或者用静态站点生成器做一个图库页面，支持按标签筛选。
这个投入不大，但收益很高。团队新人进来，能快速找到相关图，不用问人。
6.4 图的评审与反馈闭环
图评审和代码评审一样，需要闭环。我的流程是：
- 图定义改动提交 PR。
- 渲染出 SVG，附在 PR 里。
- 评审人评论，可以针对具体节点或边。
- 修改后重新渲染，直到通过。
- 合并后，图自动部署到文档站点。
这个闭环的关键是评审人能看到图。如果 PR 里只有 YAML diff，评审人很难想象最终效果。附上 SVG 截图，评审效率会高很多。
6.5 长期维护的心得
图系统维护了两年多，我最大的体会是：图的价值在于持续更新，不在于一次画得多漂亮。一张每月更新一次的普通图，比一张一年没变的精美图有价值得多。
所以，降低更新成本是核心。文本驱动、自动布局、CI 渲染、版本管理，所有这些手段都是为了让你改图时没有心理负担。改一个节点，跑一条命令，提交，完事。成本越低，更新越频繁，图越有价值。
另外，不要追求大而全的图。一张图只回答一个问题，拆成多张，每张都简单清晰。图与图之间用链接关联，形成图系统。这样既好维护，又好阅读。
最后分享一个小技巧：给图定义文件加一个 README，写清楚目录结构、命名规范、渲染命令、常见问题。新人接手时，看 README 就能上手，不用口口相传。这个 README 本身也是项目资产的一部分，值得花时间写好。
