1. 从一张草图到一套系统：diagram-design 到底在解决什么问题
第一次看到 diagram-design 这个标题，很多人会以为它只是某个画图工具的皮肤或者模板集合。但真正做过系统设计、技术方案评审、跨团队沟通的人会明白，图从来不是“画着好看”的装饰品，而是把复杂逻辑压缩成可传递信息的工程手段。diagram-design 的核心，就是围绕“如何让一张图在信息密度、可读性、可维护性之间取得平衡”这件事，建立一套可复用的设计方法与落地流程。
我在过去几年里参与过不少系统重构和方案评审，最深的感受是：大部分技术讨论卡住，不是因为问题本身有多难，而是因为每个人脑子里的“图”不一样。有人画的是部署拓扑，有人想的是数据流，还有人关注的是状态迁移。diagram-design 要解决的，正是这种“图不对版”的沟通损耗。它适合系统架构师、技术负责人、产品经理，也适合任何需要把抽象逻辑讲清楚的一线开发者。
这篇文章不会只停留在“怎么画好看”的层面。我会把 diagram-design 拆成设计思路、核心细节、实操流程、问题排查四个部分，结合我实际踩过的坑，讲清楚每一步为什么这么做、参数怎么定、哪些地方最容易翻车。如果你正在为方案评审画图、为文档配架构图、或者想建立团队内部的图示规范，这篇内容可以直接拿去参考。
2. 内容整体设计与思路拆解
2.1 为什么 diagram-design 不是“选个工具”那么简单
很多人一上来就问：用什么工具画图？是 draw.io、Excalidraw、PlantUML 还是 Mermaid？这个问题本身就把方向带偏了。工具只是最后一步的载体，diagram-design 的真正起点是“信息分层”。
我习惯把一张图要承载的信息分成三层：结构层、语义层、视觉层。结构层决定图里有哪些节点、哪些连线、哪些分组；语义层决定每个节点代表什么、连线是什么含义、方向是否重要；视觉层才是颜色、字体、间距、图标这些表现手法。大部分图看起来乱，不是视觉层没调好，而是结构层和语义层没想清楚就急着打开工具。
diagram-design 的思路是先锁定结构层，再用语义层校验，最后才进入视觉层。这个顺序不能反。我见过太多人先选了一套漂亮的配色，结果画到一半发现节点关系根本理不顺，只能推倒重来。先结构后视觉，看起来慢，实际上省掉了大量返工时间。
2.2 三种常见图示场景的选型逻辑
diagram-design 覆盖的场景很多，但落到实际工作中，最常遇到的是三类：架构拓扑图、流程时序图、状态迁移图。这三类图的设计逻辑完全不同，不能用同一套模板硬套。
架构拓扑图的核心是“边界”和“依赖”。画的时候要先确定系统边界在哪里，哪些是内部组件，哪些是外部依赖，然后才是它们之间的调用关系。这类图最怕的是把不同层级的组件混在一起画，比如把数据库和业务服务放在同一水平线上，读者根本分不清谁依赖谁。
流程时序图的核心是“顺序”和“条件”。它要回答的是“先发生什么、后发生什么、什么情况下走哪条分支”。这类图最容易犯的错误是分支条件写得太模糊，比如只写“判断成功”，但不写判断依据是什么。我一般要求把条件写成可验证的表达式，哪怕图会因此变长，也比事后扯皮强。
状态迁移图的核心是“状态”和“触发条件”。它描述的是一个对象在生命周期内如何从一个状态跳到另一个状态。这类图的关键是穷举状态和迁移条件，不能有“其他情况”这种模糊出口。一旦出现“其他”，就说明状态设计有漏洞。
2.3 从“一次性画图”到“可维护图示资产”的转变
diagram-design 还有一个容易被忽略的价值：它把图从“一次性消耗品”变成了“可维护资产”。大部分人手动画一张图，发到群里，过两周代码改了，图就过期了，没人知道它已经不准了。这种图不仅没用，还会误导后来的人。
我的做法是：凡是会随代码演进的图，尽量用文本化方式描述，比如用声明式语法写节点和连线，这样图可以跟着代码一起进版本库，改代码的时候顺手改图，评审的时候也能看到图的 diff。diagram-design 在设计之初就考虑了这种“图即代码”的路径，虽然它不强制你用某种工具，但它的结构分层思路天然适合文本化表达。
注意：不是所有图都值得文本化。一次性的讨论草图、白板上的临时推演，手画反而更快。判断标准是：这张图会不会被第二次、第三次引用？会，就值得文本化；不会，就怎么快怎么来。
3. 核心细节解析与实操要点
3.1 节点设计：一个节点只表达一件事
节点是图的基本单元。diagram-design 对节点的第一条要求是：一个节点只表达一件事。听起来像废话，但实际操作中，我见过太多节点里塞了三四层信息，比如一个框里同时写了服务名、部署环境、负责人、端口号。这种节点在图上看起来信息量很大，实际上读者根本抓不住重点。
我的做法是给节点定义“主标签”和“副标签”。主标签是节点名，必须简短、唯一、可引用；副标签是补充信息，比如版本、环境、备注。主标签控制在 12 个字符以内，副标签不超过两行。超过这个量，就说明这个节点该拆了。
节点命名还有一个坑：不要用缩写。你以为“SVC-A”大家都懂，过两周新同事进来，根本不知道这是什么。命名规则我一般建议用“领域+职责”的方式，比如“订单服务”“支付网关”“用户数据库”，看到名字就知道它干什么。
3.2 连线设计：方向、标签、粗细都有含义
连线是图里最容易画乱的部分。diagram-design 对连线的要求是：每一条线都必须有明确含义，不能有装饰性连线。
方向方面，我习惯用“调用方向”而不是“数据流向”。因为调用方向更稳定，数据流向可能来回变。如果确实要表达数据流向，就用不同线型区分，比如实线表示同步调用，虚线表示异步消息。
标签方面，连线上一定要写清楚“传什么”或“做什么”。只画一条线不写标签，等于没画。标签要具体，比如“提交订单”“查询库存”“推送通知”，不要写“调用”“请求”这种泛词。
粗细方面，我一般用线宽表示调用频率或数据量级。高频调用用粗线，低频用细线。但这条规则不是必须的，如果图里线太多，粗细反而会增加视觉噪音，那就统一线宽，用颜色或标签区分。
| 连线属性 | 推荐做法 | 常见错误 |
|---|---|---|
| 方向 | 调用方向优先 | 方向来回变，读者迷路 |
| 标签 | 写具体动作或数据 | 只写“调用”“请求” |
| 线型 | 实线同步，虚线异步 | 全用实线，分不清 |
| 粗细 | 表示频率或量级 | 线太多时统一线宽 |
| 颜色 | 按领域或层级分组 | 颜色太多，失去重点 |
3.3 分组与边界：让读者知道“哪里是里面，哪里是外面”
分组是 diagram-design 里最容易被低估的设计手段。一张图如果没有分组，所有节点平铺，读者很难判断哪些组件属于同一个系统、哪些是外部依赖。分组就是在告诉读者：“这个框里的东西是一伙的。”
我一般用两种分组方式：边界框和背景色块。边界框适合表达系统边界、网络分区、部署单元；背景色块适合表达逻辑分组，比如“用户域”“订单域”“支付域”。两种方式可以叠加使用，但不要超过两层，否则图会变得很碎。
分组命名也有讲究。不要写“其他”“杂项”这种词，一旦出现这种分组，说明你的分类逻辑有问题。分组名要和节点名一样具体，比如“订单服务集群”“第三方支付依赖”“内部消息队列”。
提示：分组框的边距要留够。我见过太多图，节点紧贴着分组框的边，看起来像被裁掉了一样。一般建议分组框内边距至少是节点间距的 1.5 倍，视觉上才舒服。
3.4 视觉层：颜色、字体、间距的克制使用
视觉层是最后一步，也是最容易过度设计的一步。diagram-design 的原则是：视觉手段只用来强化结构，不用来装饰。
颜色方面，我一般限制在 3 到 5 种。一种主色表示核心组件，一种辅助色表示外部依赖，一种警示色表示风险或待办，其余用灰色。颜色太多，读者会以为每种颜色都有特殊含义，反而增加认知负担。
字体方面，统一用无衬线字体，字号不超过三档。节点主标签最大，副标签次之，连线标签最小。不要用斜体、下划线、全大写这些花哨样式，除非有明确的语义区分。
间距方面，节点之间的水平间距和垂直间距要一致。我习惯用 8 的倍数作为间距单位，比如 16、24、32。这样图看起来有节奏感，不会忽松忽紧。对齐也很重要，同一层级的节点尽量左对齐或居中对齐，不要随手摆放。
4. 实操过程与核心环节实现
4.1 第一步：明确图的读者和用途
动手画之前，先回答三个问题：这张图给谁看？他们关心什么？看完之后要做什么决策？
给管理层看的架构图，重点在系统边界和关键依赖，细节可以省略；给开发看的时序图，重点在分支条件和异常路径，正常流程反而可以简化；给运维看的部署图，重点在网络分区和实例数量，业务逻辑不用展开。
我一般会在图的最上方或文档开头写一句话说明：“本图面向 XX 角色，用于 XX 决策，省略了 XX 细节。”这句话看起来简单，但能省掉大量“为什么这里没画”的追问。
4.2 第二步：用文本先列节点和关系
这一步是 diagram-design 的核心实操。不要打开画图工具，先用纯文本把节点和关系列出来。
我通常用这样的格式：
节点： - 订单服务（核心） - 支付网关（外部） - 订单数据库（核心） - 消息队列（基础设施） 关系： - 订单服务 -> 支付网关：发起支付 - 订单服务 -> 订单数据库：读写订单 - 订单服务 -> 消息队列：发送支付结果事件 - 支付网关 -> 消息队列：异步回调这个文本清单就是图的“骨架”。列完之后，先自己读一遍，看看有没有逻辑漏洞，比如某个节点没有入边也没有出边，那它可能是多余的；某个关系方向反了，那可能是理解错了。
4.3 第三步：确定布局和分组
文本清单确认后，开始确定布局。布局的核心是“让主要信息流从左到右或从上到下自然流动”。
我一般把调用发起方放在左侧或上方，被调用方放在右侧或下方。如果是循环调用，就用环形布局或者分层布局，不要画成蜘蛛网。
分组在这一步确定。把属于同一系统或同一层级的节点圈在一起，给分组命名。分组框不要重叠，如果重叠了，说明分组逻辑有问题，需要重新划分。
4.4 第四步：选择工具并落地
工具选择取决于图的用途和维护方式。如果是一次性讨论图，Excalidraw 或手绘最快；如果是需要进版本库的图，PlantUML 或 Mermaid 更合适；如果是需要精细排版的对外文档，draw.io 或 Figma 更灵活。
我个人的习惯是：内部讨论用 Excalidraw，正式文档用 Mermaid，对外材料用 draw.io 导出高清图。Mermaid 的好处是纯文本，改起来快，diff 也清晰。但 Mermaid 的布局控制力弱，复杂图容易乱，这时候就换 draw.io 手动调。
不管用什么工具，落地时都要检查三件事：节点命名是否统一、连线标签是否完整、分组边界是否清晰。这三件事检查完，图的基本质量就有保障了。
4.5 第五步：评审与迭代
图不是画完就结束了。diagram-design 强调“图要经过评审”。我一般会把图发给两到三个不同角色的同事，问他们同一个问题：“你能看出这个系统的核心依赖是什么吗？”如果他们的回答不一致，说明图的信息传递有问题。
评审时重点看三个地方：有没有歧义节点、有没有缺失关系、有没有过度细节。歧义节点就是名字模糊、职责不清的节点；缺失关系就是两个节点之间明明有交互但图上没画；过度细节就是画了太多实现层面的东西，掩盖了核心结构。
迭代两到三轮之后，图基本就稳定了。这时候再把它放进文档或版本库，后续改动跟着代码走。
5. 常见问题与排查技巧实录
5.1 图太乱怎么办：先删节点，再删连线
图乱的第一反应通常是“调布局”，但我的经验是：先删节点。大部分图乱，是因为节点太多，而不是布局不好。把非核心节点删掉，或者合并到分组里，图立刻清爽一半。
删节点的标准是：这个节点删掉之后，读者还能不能理解核心逻辑？能，就删；不能，就留。删完节点再删连线，只保留有明确语义的连线，装饰性连线全部去掉。
5.2 连线交叉太多怎么办：调整层级或拆分图
连线交叉是布局问题，但根因往往是层级没分好。如果两个节点之间的连线要穿过好几个其他节点，说明它们不在同一层级，应该用分组或分层来重新组织。
如果调整层级后交叉还是太多，那就拆图。一张图只讲一件事，讲依赖就只画依赖，讲流程就只画流程。拆成两张图，比一张图里塞所有信息更清晰。
5.3 图过期了没人更新怎么办：把图放进版本库
图过期是常态，解决办法不是靠自觉，而是靠流程。我的做法是：凡是和代码强相关的图，都用文本化方式描述，和代码放在同一个版本库里。改代码的时候，评审人能看到图有没有同步更新。如果图没更新，评审就不通过。
这个流程一开始会有点麻烦，但跑顺之后，图的准确率会大幅提升。毕竟，没人愿意在评审时被问“你这图怎么和代码不一致”。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 排查思路 | 解决建议 |
|---|---|---|---|
| 图看起来乱 | 节点太多或层级不清 | 数节点数量，检查分组 | 删非核心节点，重新分组 |
| 连线交叉严重 | 层级没分好或图太复杂 | 检查节点是否跨层 | 调整层级或拆图 |
| 读者理解不一致 | 节点命名模糊或标签缺失 | 让不同角色读图 | 统一命名，补全标签 |
| 图过期无人更新 | 图与代码分离 | 检查图是否在版本库 | 文本化描述，进版本库 |
| 评审时争议多 | 边界或条件不明确 | 检查分组和分支条件 | 明确边界，写清条件 |
| 视觉太花哨 | 颜色字体过多 | 数颜色数量和字号 | 限制在 3 到 5 色，三档字号 |
5.5 几个我踩过的坑
第一个坑是“过度追求对称”。我曾经为了让图看起来整齐，强行把节点摆成对称布局，结果连线绕来绕去，读者反而看不懂。后来我明白了，布局的第一目标是“信息流清晰”，不是“好看”。不对称但信息流顺畅的图，比对称但绕路的图好得多。
第二个坑是“用颜色代替标签”。有一段时间我喜欢用不同颜色区分不同系统，结果打印出来全是灰的，颜色区分完全失效。后来我改成颜色加标签双重区分，即使黑白打印也能看懂。
第三个坑是“图里写代码细节”。我曾经在架构图里写了具体的接口路径和参数名，结果接口一改，图就过期了。后来我把这些细节移到文档正文里，图只保留结构关系，图的寿命立刻变长了。
提示：图的生命周期取决于它承载的信息的稳定性。结构关系比实现细节稳定，所以图里尽量画结构，少画实现。
6. 从 diagram-design 延伸出的团队协作习惯
diagram-design 表面上是一套画图方法，实际上它改变的是团队沟通方式。当大家都用同一套节点命名规则、同一套连线语义、同一套分组逻辑时，图就变成了一种“通用语言”。新同事进来，看几张图就能快速理解系统结构；跨团队评审时，大家对着同一张图讨论，减少了很多“我以为你说的是另一个东西”的扯皮。
我现在的习惯是：任何超过三句话才能说清的技术方案，都先画一张图。画图的过程本身就是梳理逻辑的过程，很多漏洞在画图阶段就会暴露出来。图画完了，方案也就想清楚了。
如果你刚开始接触 diagram-design，我的建议是从一张小图开始，不要一上来就画整个系统。先画一个模块的依赖关系，把节点、连线、分组这三件事练熟，再逐步扩大范围。画上十张图之后，你会发现自己看系统的方式都变了。
