1. 从一张草图到一套系统：diagram-design 到底在解决什么问题
第一次看到 diagram-design 这个词，很多人会以为它只是一个画图工具的代称。但真正在项目里摸爬滚打过几年的人会明白，它指向的是一套完整的“图表设计体系”——从需求梳理、结构抽象、视觉编码，到最终交付一份别人能看懂、能复用、能维护的图表资产。我见过太多团队，画架构图靠拖拽，改一版就崩一版，最后没人敢动那张图，因为谁也不知道哪根线代表什么。diagram-design 要解决的，恰恰是这个“图到用时方恨乱”的老大难问题。
说得直白一点，diagram-design 的核心价值在于把“画图”这件事从个人手艺变成可复用的工程方法。它适合三类人：一是需要频繁输出架构图、流程图、时序图的技术同学；二是要跟产品、运营、设计多方对齐信息的产品经理；三是带团队、需要统一文档规范的技术负责人。不管你是刚入行的新手，还是画了十年图的老手，只要你的工作里涉及“把复杂信息用图形讲清楚”，这套东西就能直接拿去用。
我自己的经历是，早年间做项目汇报，一张系统架构图改了七版，每次评审都被挑出“这里逻辑不对”“那里层级混乱”。后来我才意识到，问题不在画图技巧，而在于画之前没有想清楚“这张图要回答什么问题”。diagram-design 的第一性原则就是：先定义信息结构，再决定视觉表达。这个顺序一旦反过来，图就会越画越乱。
接下来的内容，我会从整体设计思路、核心细节、实操过程、常见问题四个维度，把 diagram-design 拆开揉碎讲清楚。每一部分都附带我实际踩过的坑和验证过的做法，你可以直接抄作业，也可以根据自己团队的情况做调整。
2. 整体设计与思路拆解：为什么先结构后视觉
2.1 图表设计的三个层次：信息层、结构层、视觉层
很多人画图是从视觉层开始的——打开工具，拖一个方框，再拖一个箭头，边画边想。这种做法在画简单流程图时勉强能用，但一旦涉及多系统交互、多角色协作，就会迅速失控。diagram-design 的思路是把图表设计拆成三个层次，自下而上依次处理。
信息层解决的是“这张图要表达哪些事实”。比如一个订单系统，涉及用户、订单服务、支付服务、库存服务、消息队列，这些实体以及它们之间的调用关系，就是信息层的内容。这一层不关心谁画得好看，只关心信息是否完整、准确。
结构层解决的是“这些事实之间是什么关系”。是包含关系、依赖关系、数据流向关系，还是时序关系？不同的关系类型决定了图的骨架。比如依赖关系适合用有向图，时序关系适合用序列图，层级关系适合用树状图。结构层一旦确定，图的“形状”就基本定了。
视觉层解决的是“怎么让人一眼看懂”。颜色、线型、间距、对齐、标注，这些都是视觉层的手段。视觉层做得好，图会自己说话；做得不好，信息再准确也没人愿意看。
我见过不少团队跳过前两层直接做视觉层，结果就是图很漂亮但没人看得懂。正确的做法是：先用文字把信息层和结构层写清楚，确认无误后再进入视觉层。这一步多花十分钟，后面能省两小时。
2.2 为什么选择“约束驱动”而不是“自由发挥”
diagram-design 的另一个核心思路是约束驱动。什么意思？就是提前定义好一套规则，比如“所有外部系统用灰色填充”“所有数据存储用圆柱体”“所有异步调用用虚线箭头”。这些规则一旦确定，画图的人就不需要每次纠结“这个该用什么颜色”“那个该用什么形状”。
约束驱动的好处有三个。第一是降低认知负担，画图的人可以把精力放在信息本身，而不是视觉决策上。第二是保证一致性，同一个项目里不同人画的图看起来像一套东西，读者不需要重新学习图例。第三是便于维护，当系统发生变化时，只需要按规则修改对应部分，不会牵一发而动全身。
我自己的做法是，每个项目开始前先花半小时定一份“图表规范”，内容包括：实体类型与对应形状、关系类型与对应线型、颜色语义、字体大小层级、标注格式。这份规范不需要很复杂，一页纸就够，但必须让所有参与画图的人过一遍。实测下来，这一步能让后续的返工率降低至少一半。
2.3 工具选型：为什么我不推荐一上来就用重型工具
说到画图工具，市面上的选择很多，从轻量的在线白板到专业的建模软件都有。我的建议是：根据图的“生命周期”来选工具，而不是根据功能多少来选。
如果这张图只是用来临时讨论、画完就扔，那用什么都行，白板、便签、甚至手绘拍照都可以。但如果这张图要进入文档、要被多人维护、要跟着项目迭代，那就必须选一个支持“文本化定义”的工具。什么叫文本化定义？就是用代码或结构化文本描述图的内容，工具负责渲染。这样做的好处是，图的内容可以进版本控制，可以 diff，可以 review，可以多人协作而不冲突。
我试过用纯拖拽工具维护一张二十个节点的架构图，每次改都要手动调整连线，改完还要检查有没有对齐、有没有重叠，非常痛苦。后来换成文本化定义的方式，改图就是改几行描述，渲染出来自动布局，效率提升非常明显。当然，文本化工具的学习曲线会陡一点，但一旦过了那个坎，就再也回不去了。
提示：工具选型没有绝对的好坏，关键是匹配图的用途。临时讨论用轻量工具，长期维护用文本化工具，这是我自己验证过最稳的组合。
3. 核心细节解析与实操要点：从信息梳理到视觉编码
3.1 信息梳理：怎么把一堆零散需求变成结构化清单
信息梳理是 diagram-design 的第一步，也是最容易被忽视的一步。很多人拿到需求就开始画，画到一半发现漏了东西，又回头补，补完发现布局全乱了。正确的做法是先做信息梳理，把要画的内容列成清单。
具体怎么做？我通常分三步。第一步是“穷举”，把所有相关的实体、角色、系统、模块、数据流都列出来，不管重不重要，先写下来。第二步是“归类”，把列出来的东西按类型分组，比如“外部角色”“内部服务”“数据存储”“消息通道”。第三步是“定关系”，明确每组之间、每个实体之间的关系类型。
举个例子，假设你要画一个“用户下单”的流程图。穷举阶段你会列出：用户、前端页面、订单服务、支付服务、库存服务、数据库、消息队列、物流系统。归类阶段你会把它们分成：外部角色（用户）、前端（页面）、后端服务（订单、支付、库存）、存储（数据库）、中间件（消息队列）、外部系统（物流）。定关系阶段你会明确：用户调用前端，前端调用订单服务，订单服务调用支付和库存，订单服务写数据库，订单服务发消息到队列，物流系统消费队列消息。
这份清单写完之后，图的骨架就出来了。接下来无论用什么工具画，都只是把这份清单翻译成图形而已。我自己的经验是，信息梳理花的时间越多，后面画图越顺。通常一个中等复杂度的图，信息梳理要占整个工作量的四成左右。
3.2 结构抽象：选对图类型比画得好看重要一百倍
信息梳理完之后，下一步是选择图类型。不同的信息结构适合不同的图类型，选错了图类型，信息就会表达不清。
| 信息结构 | 推荐图类型 | 适用场景 | 不适用场景 |
|---|---|---|---|
| 层级包含 | 树状图、思维导图 | 模块拆分、组织架构 | 多对多依赖 |
| 调用依赖 | 有向图、架构图 | 系统交互、服务依赖 | 时序敏感场景 |
| 时序交互 | 序列图、时序图 | 接口调用、消息流转 | 静态结构展示 |
| 状态流转 | 状态机图 | 订单状态、工单流转 | 多系统交互 |
| 数据流向 | 数据流图 | 数据处理、ETL流程 | 实时交互 |
选图类型的核心原则是：让图的“形状”匹配信息的“结构”。比如你要表达“订单从创建到完成经过哪些状态”，那就用状态机图，因为状态流转本身就是线性的、有明确节点的。如果你用架构图去画状态流转，读者就会困惑：这些方框之间到底是什么关系？
我踩过的一个坑是，曾经用序列图画一个多服务的依赖关系，结果画出来非常别扭，因为序列图强调时间顺序，而依赖关系并不关心谁先谁后。后来换成有向图，同样的信息，清晰度提升了一个档次。所以选图类型这一步，一定要根据信息的本质结构来定，不要因为某种图看起来“高级”就硬套。
3.3 视觉编码：颜色、线型、形状的语义化使用
视觉编码是 diagram-design 的最后一层，也是最容易出彩的一层。但前提是前两层已经做扎实了，否则视觉层做得再好也是空中楼阁。
颜色方面，我的原则是“少即是多”。一张图里主色不要超过三种，每种颜色对应一个明确的语义。比如蓝色代表内部服务，绿色代表外部系统，橙色代表数据存储。不要为了好看而用渐变色、彩虹色，那样只会分散注意力。
线型方面，实线通常表示同步调用或强依赖，虚线表示异步调用或弱依赖，点线表示可选或已废弃。箭头方向表示调用方向或数据流向。这些约定一旦定下来，就要在所有图里保持一致。
形状方面，方框表示服务或模块，圆柱体表示数据库，菱形表示判断或网关，圆角矩形表示外部系统。形状的选择要符合读者的直觉，不要发明奇怪的形状，除非你有非常明确的理由。
注意：视觉编码的核心是“一致性”而不是“美观”。同一套图里，同样的语义必须用同样的视觉元素，否则读者会困惑。我见过一张图里用蓝色表示服务，另一张图里用蓝色表示数据库，放在一起看就很容易误解。
3.4 标注与注释：让图自己说话的关键细节
一张好的图，应该不需要额外解释就能看懂。但现实中很多图需要配一大段文字说明，这就说明标注没做好。
标注的原则是：在图上直接写清楚关键信息，而不是留给读者去猜。比如一条调用线上，应该标注接口名称或调用动作；一个服务方框里，应该写清楚服务名和职责；一个数据存储旁边，应该注明存储类型和关键数据。
注释的使用要克制。注释适合补充“为什么”而不是“是什么”。比如某个服务为什么被标记为废弃，某个调用为什么是异步的，这些用注释说明是合理的。但如果只是重复图上的信息，那就没必要。
我自己的习惯是，画完图之后先放一放，过半小时再回来看。如果第一眼能看懂主要信息，说明标注到位了；如果第一眼不知道从哪看起，那就需要调整布局或补充标注。这个“冷却后再看”的方法非常有效，推荐你也试试。
4. 实操过程与核心环节实现：一套可复现的图表设计流程
4.1 环境准备与工具配置
在开始画图之前，先花点时间把环境和工具配置好。这一步看起来琐碎，但能省掉后面很多麻烦。
如果你选择文本化定义的工具，通常需要先安装运行时环境和渲染引擎。以常见的文本化图表工具为例，基本流程是：安装运行时，安装图表渲染库，配置编辑器插件，创建项目目录。具体命令根据工具不同会有差异，但思路是一样的。
我自己的配置清单是这样的：一个支持语法高亮的编辑器，一个能实时预览的插件，一个版本控制仓库用来存图源文件，一个导出脚本用来生成图片。这套配置搭好之后，画图就是写文本、预览、导出三步，非常顺畅。
提示：图源文件一定要进版本控制。我见过太多团队把图导出成图片后就丢了源文件，后来想改都改不了，只能重画。源文件进仓库，改图就是改代码，可以 review，可以回滚，这是长期维护的关键。
4.2 从需求到图源：一个完整案例的拆解
假设我们要画一个“内容发布流程”的图，涉及作者、编辑、审核系统、发布系统、内容库。我按 diagram-design 的流程走一遍。
第一步，信息梳理。穷举实体：作者、编辑、审核系统、发布系统、内容库、通知系统。归类：角色（作者、编辑）、内部系统（审核、发布、通知）、存储（内容库）。定关系：作者提交内容给编辑，编辑提交给审核系统，审核通过后通知发布系统，发布系统写入内容库，发布系统通知作者和编辑。
第二步，结构抽象。这个流程的核心是“状态流转+角色交互”，所以适合用带泳道的流程图，泳道区分角色和系统，流程节点表示状态变化。
第三步，视觉编码。作者和编辑用不同颜色的泳道，审核系统用菱形表示判断节点，发布系统用方框，内容库用圆柱体，通知用虚线箭头。
第四步，写图源。根据选定的工具语法，把上述内容翻译成结构化文本。这一步的关键是保持命名一致，比如“审核系统”在所有地方都叫同一个名字，不要一会儿叫“审核服务”一会儿叫“审核模块”。
第五步，渲染预览。生成图之后检查布局是否合理，连线是否交叉过多，标注是否清晰。如果有问题，回到图源调整，而不是在渲染结果上手动修改。
第六步，导出交付。根据用途导出不同格式，文档用 PNG 或 SVG，演示用高分辨率图片，源文件留在仓库里。
这套流程走下来，一个中等复杂度的图大概需要一到两个小时，其中信息梳理和结构抽象占一半时间，写图源和调整占另一半。相比边画边想的方式，前期多花的时间会在后期成倍省回来。
4.3 参数计算与布局优化：让图更易读的量化方法
图表的布局不是凭感觉调的，有一些可以量化的原则。我总结了几条自己常用的。
节点间距方面，同一层级的节点之间保持等距，间距通常是节点宽度的 0.5 到 1 倍。间距太小会显得拥挤，太大则浪费空间且增加连线长度。
连线交叉方面，尽量减少交叉。如果交叉不可避免，尽量让交叉发生在空白区域，不要压在节点上。减少交叉的一个技巧是调整节点顺序，把关联紧密的节点放在相邻位置。
层级深度方面，一张图的层级不要超过五层。超过五层说明信息结构太复杂，应该拆成多张图。我见过一张图有八九层嵌套，读者根本找不到重点。
文字大小方面，标题字号是正文字号的 1.5 倍左右，标注字号是正文字号的 0.8 倍左右。字号层级不要超过三级，否则会显得杂乱。
这些参数不是死规定，但可以作为起点。实际调整时，以“第一眼能看懂”为标准，而不是以“符合某个数值”为标准。
4.4 导出与交付：不同场景下的格式选择
图的最终用途决定了导出格式。我通常分三种场景。
文档嵌入场景，用 SVG 格式。SVG 是矢量图，放大不模糊，文件小，适合放在网页或在线文档里。缺点是某些老旧的文档系统不支持 SVG，那就退而求其次用 PNG。
演示汇报场景，用高分辨率 PNG。分辨率至少 1920 像素宽，确保投影时清晰。如果图很大，可以导出 PDF，演示时放大局部。
打印场景，用 PDF 或高分辨率 PNG。打印对分辨率要求更高，通常需要 300 DPI 以上。如果图里有细线，打印前要检查线宽是否足够，太细的线打印出来会断断续续。
注意：导出之前一定要检查图例和标注是否完整。我见过不少图在编辑器里看着没问题，导出后图例被裁掉了，或者标注文字溢出边界。导出后花十秒钟扫一眼，能避免很多尴尬。
5. 常见问题与排查技巧实录：那些文档里不会写的坑
5.1 图越画越乱怎么办：三个止损信号
画图过程中如果出现以下三个信号，说明需要停下来重新梳理，而不是继续硬画。
第一个信号是“连线交叉超过节点数量的一半”。这说明节点布局不合理，或者信息结构本身有问题。这时候应该回到结构层，重新考虑图类型是否选对了。
第二个信号是“同一张图里出现三种以上线型或五种以上颜色”。这说明视觉编码失控了，读者需要花大量精力去记图例。这时候应该精简视觉元素，把不重要的信息去掉或合并。
第三个信号是“自己画完看不懂”。这不是玩笑，我确实遇到过画到后面自己都迷糊的情况。这时候最好的做法是关掉编辑器，用白纸把核心信息重新写一遍，然后再回来画。
5.2 多人协作时图不一致：统一规范的落地方法
多人协作画图，最大的问题是风格不一致。A 同学用蓝色表示服务，B 同学用蓝色表示数据库，放在一起就乱了。
解决方法是把图表规范落地成可执行的检查项。具体做法是：在项目仓库里放一份规范文档，内容包括颜色语义表、形状语义表、线型语义表、命名规则。每次提交图源文件时，对照规范检查一遍。如果团队用代码评审流程，可以把规范检查作为评审项之一。
我自己的团队还做了一个简单的检查脚本，自动扫描图源文件里的颜色和形状使用，如果发现不在规范内的值就报警。这个脚本不复杂，但效果很好，能挡住大部分不一致的问题。
5.3 图源文件冲突：版本控制下的合并策略
文本化图源文件的一个好处是可以进版本控制，但多人同时修改同一个文件时，合并冲突是难免的。
减少冲突的策略有三个。第一是拆分文件，把一张大图拆成多个小文件，每个人改自己的部分，冲突概率大大降低。第二是约定修改顺序，比如先改节点定义再改连线，避免同时改同一区域。第三是频繁提交，不要攒一大堆修改再提交，小步提交更容易合并。
如果冲突还是发生了，处理原则是：先看冲突区域，理解双方的修改意图，然后手动合并。不要直接选“接受我的”或“接受对方的”，那样会丢信息。合并完之后一定要重新渲染预览，确认图没有画错。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 图渲染失败 | 语法错误 | 查看渲染日志 | 根据日志定位到具体行修改 |
| 连线交叉过多 | 节点顺序不合理 | 观察交叉集中区域 | 调整节点顺序或换图类型 |
| 导出图片模糊 | 分辨率不足 | 检查导出设置 | 提高分辨率或改用 SVG |
| 文字溢出边界 | 节点尺寸太小 | 检查节点宽度 | 增大节点尺寸或缩短文字 |
| 图例缺失 | 导出时被裁剪 | 检查导出边界 | 调整画布尺寸或图例位置 |
| 多人修改冲突 | 同时改同一文件 | 查看版本控制记录 | 拆分文件或约定修改顺序 |
| 图看不懂 | 信息层或结构层有问题 | 让同事试读 | 回到信息梳理重新设计 |
5.5 我踩过的三个典型坑
第一个坑是“过度设计”。早期我画图喜欢加很多装饰，阴影、渐变、图标，结果图看起来很花哨但信息密度很低。后来我意识到，图的核心价值是传递信息，不是展示设计技巧。现在我的图都很朴素，但信息清晰。
第二个坑是“命名不一致”。同一个服务，在图里叫“订单服务”，在文档里叫“订单系统”，在代码里叫“order-service”，读者需要来回对照。后来我定了一条规则：图里的命名必须和代码里的命名一致，这样读者可以直接对应。
第三个坑是“图不更新”。系统改了，图没改，过段时间图就失效了。后来我把图源文件放进代码仓库，和代码一起提交，代码改图也改，这样图就不会过期。这个做法看起来简单，但坚持下来效果非常好。
6. 从单张图到图表体系：diagram-design 的扩展思路
6.1 建立项目级的图表库
单张图解决单点问题，图表库解决系统问题。当一个项目有十几张图的时候，就需要考虑建立图表库了。
图表库的核心是“可检索”和“可复用”。可检索意味着每张图有明确的标题、描述、标签，需要的时候能快速找到。可复用意味着图里的公共元素（比如服务图标、颜色定义、布局模板）可以抽出来共享，改一处就能全局生效。
我自己的做法是在仓库里建一个diagrams目录，下面按模块分子目录，每个子目录里放图源文件和导出的图片。同时维护一个索引文件，列出所有图的标题、路径、最后更新时间。这个索引文件用脚本自动生成，不需要手动维护。
6.2 图表与文档的联动
图不是孤立存在的，它通常和文档一起使用。理想的状态是图和文档联动，改图的时候文档自动更新，改文档的时候图也能同步。
实现联动的一个方法是“单一数据源”。把图里的关键信息（比如服务列表、接口列表）抽成一个结构化数据文件，图和文档都从这个文件生成。这样改数据文件，图和文档同时更新，不会出现不一致。
这个方法实施起来有一定成本，适合对一致性要求高的项目。如果项目规模不大，手动同步也可以，但一定要定好同步的时机和责任人，否则很容易漏掉。
6.3 图表规范的持续演进
图表规范不是定一次就永远不变的。随着项目发展，新的实体类型会出现，新的关系类型会出现，规范也需要跟着更新。
我的做法是每个季度回顾一次图表规范，看看有没有需要新增或调整的地方。回顾的时候会收集团队成员的反馈，比如“最近画图时遇到什么不方便的地方”“有没有哪种信息类型没有对应的视觉元素”。根据反馈调整规范，然后同步给所有人。
规范更新后，旧图不一定要全部重画，但新图必须按新规范来。如果旧图有重大修改，顺便按新规范调整。这样规范就能持续演进，而不是变成一纸空文。
6.4 图表设计的个人修炼路径
最后说点个人体会。图表设计这件事，入门容易精通难。入门只需要学会用工具，精通需要理解信息结构、视觉认知、协作流程。
我自己的修炼路径是这样的：第一阶段是“能画出来”，不管好坏，先把信息表达出来。第二阶段是“画得清楚”，开始注意布局、颜色、标注，让图更容易看懂。第三阶段是“画得一致”，建立规范，让所有图看起来像一套东西。第四阶段是“画得高效”，用文本化工具和自动化脚本提升效率。第五阶段是“画得少”，意识到不是所有信息都需要画图，有些用文字或表格更合适。
这个路径没有捷径，只能靠多画、多看、多改。但每过一个阶段，你都会发现之前画的图有很多可以改进的地方，这种“回头看觉得以前画得烂”的感觉，恰恰说明你在进步。
提示：如果你刚开始接触 diagram-design，建议从一张小图开始，完整走一遍信息梳理、结构抽象、视觉编码、导出交付的流程。走完之后再回头看这篇文章，会有更深的体会。
