1. 从一张草图到一套系统：diagram-design 到底在解决什么问题
第一次看到 diagram-design 这个词，很多人会以为它只是一个画图工具或者某个模板库。但真正在项目里摸爬滚打过几年的人会明白，它本质上是一套关于“如何把复杂信息变成可读图形”的设计方法论。你手里可能有一堆零散的需求文档、一段绕来绕去的业务流程、一个包含十几个模块的系统架构，甚至只是一张白板上随手画的鬼画符。diagram-design 要做的，就是把这些东西变成别人一眼能看懂、能直接拿去讨论、能落地执行的图。
我最早接触这类工作是在一个内部工具重构项目里。当时团队有五个人，每个人对“订单状态流转”的理解都不一样，产品说一套、开发说一套、测试又按自己的理解写用例。后来我们花了一个下午，用 diagram-design 的思路把整个状态机画出来，贴到墙上，所有争议当场消失。从那以后我就意识到，图不是装饰品，图是沟通工具，而 diagram-design 就是让这个沟通工具变得可靠的那套手艺。
这篇文章适合谁看？如果你是产品经理、技术负责人、架构师，或者任何需要把复杂逻辑讲清楚的人，那这里面的内容你直接拿去用。如果你只是偶尔画个流程图应付汇报，也能从里面找到让图更专业、更少被挑战的技巧。我不会讲太多理论，重点放在“怎么选、怎么画、怎么改、怎么避坑”这四个环节上，每个环节都会给出可复现的步骤和参数建议。
2. 核心思路拆解：为什么你的图总是被人说“看不懂”
2.1 信息分层：先决定什么该画，什么不该画
大部分人画图的第一反应是“把所有东西都放上去”，结果就是一张图里塞了三十个节点、五十条连线，看的人直接放弃。diagram-design 的第一个核心原则就是分层。你得先问自己：这张图是给谁看的？是给高层看全局，还是给开发看细节？如果是给高层看，那数据库表结构、接口参数这些统统不要出现；如果是给开发看，那业务背景和用户价值就可以压缩成一句话。
我通常会把信息分成三层：战略层（目标、范围、关键角色）、逻辑层（流程、状态、依赖关系）、实现层（接口、字段、部署细节）。一张图只承载一层信息，最多两层。比如画系统架构图，战略层就是“有哪些系统、它们之间是什么关系”，逻辑层是“数据怎么流、调用顺序是什么”，实现层是“用什么协议、端口号多少”。你把这三层混在一起，图就废了。
注意：如果你发现一张图里同时出现了“用户下单”和“MySQL主从同步”，那这张图大概率需要拆成两张。
2.2 视觉编码：颜色、形状、线条都有固定含义
diagram-design 里有一个容易被忽略但极其重要的点：视觉元素必须有一致的语义。你不能这张图里红色代表“异常”，下一张图里红色又代表“核心模块”。读者会疯掉的。我的习惯是建立一套自己的视觉词典，比如：
| 视觉元素 | 含义 | 使用场景 |
|---|---|---|
| 蓝色矩形 | 外部系统/用户 | 架构图、上下文图 |
| 绿色矩形 | 内部服务/模块 | 架构图、部署图 |
| 黄色菱形 | 判断/分支 | 流程图、状态图 |
| 红色虚线 | 异常流/补偿逻辑 | 流程图、时序图 |
| 灰色圆角矩形 | 数据存储 | 架构图、数据流图 |
这套词典一旦定下来，团队里所有人都按这个来，图与图之间就能互相引用，不需要每次重新解释。我见过一个团队因为没统一颜色含义，导致新来的开发把“红色模块”当成故障组件，排查了半天才发现只是画图的人随手选的色。
2.3 布局逻辑：从左到右、从上到下，还是中心辐射
布局决定了读者的阅读顺序。diagram-design 里常用的布局有三种：线性布局（从左到右或从上到下）、层级布局（从上到下逐层展开）、中心辐射布局（核心节点在中间，周边节点围绕）。选哪种取决于你要表达的关系类型。
如果是流程类，线性布局最自然，读者顺着箭头走就行。如果是组织架构或系统分层，层级布局更清晰。如果是生态图或依赖关系图，中心辐射布局能突出核心。我个人的经验是：能用线性就不用层级，能用层级就不用辐射。因为线性布局的认知成本最低，读者不需要思考“我该从哪看起”。
2.4 为什么不用现成的模板直接套
网上有很多现成的 diagram 模板，看起来很美，但直接套用往往出问题。原因很简单：模板是为通用场景设计的，而你的项目有独特的约束和重点。比如一个通用的微服务架构模板可能画了网关、服务注册、配置中心、链路追踪等一堆组件，但你的项目可能只有三个服务，连网关都没有。你硬套模板，就会画出一些根本不存在的组件，或者把不重要的东西画得很大。
diagram-design 的思路是：先理解自己的系统，再决定画什么，最后才考虑美化。模板可以参考，但不要照搬。我通常会把模板当作检查清单，看看自己有没有漏掉某个关键维度，而不是当作底图直接改字。
3. 核心细节解析与实操要点：从需求到成图的完整链路
3.1 需求转图形：如何把一段文字变成节点和连线
这是最考验功力的环节。给你一段需求描述：“用户提交订单后，系统先校验库存，如果库存不足则返回失败；如果库存充足，则锁定库存并调用支付服务；支付成功后通知发货服务，支付失败则释放库存。”你怎么把它变成图？
我的步骤是这样的：
- 提取名词：用户、订单、库存、支付服务、发货服务。这些是候选节点。
- 提取动词：提交、校验、锁定、调用、通知、释放。这些是候选连线或动作节点。
- 识别判断点：库存是否充足、支付是否成功。这些是菱形判断节点。
- 确定起点和终点：起点是“用户提交订单”，终点是“发货”或“返回失败”。
- 补充异常流：支付失败后的释放库存，库存不足后的返回失败。
这样一套下来，节点数量控制在 8 到 12 个之间，连线不超过 15 条。如果超过这个数，说明你需要拆图。我见过有人把整个电商系统画在一张图上，结果打印出来有 A0 纸那么大，没人看得清。
实操心得：提取名词和动词的时候，不要纠结于“这个算不算节点”。先全部列出来，然后再合并同类项。比如“校验库存”和“锁定库存”可以合并成一个“库存服务”节点，也可以拆成两个动作节点，取决于你的读者关心什么。
3.2 节点命名规范：让每个框都自解释
节点命名是 diagram-design 里最容易被低估的细节。一个好的节点名应该满足三个条件：唯一、具体、无歧义。我见过太多图里写着“服务A”、“模块1”、“处理”这种名字，读者根本不知道那是什么。
我的命名规则是：动词+名词或形容词+名词。比如“校验库存”比“库存校验”好，因为前者强调了动作；“支付服务”比“支付”好，因为后者可能被理解成一个动作而不是一个系统。如果是外部系统，加上“外部”前缀，比如“外部支付网关”。如果是数据存储，加上“库”或“表”后缀，比如“订单库”、“库存表”。
还有一个技巧：节点名不要超过 8 个字。超过 8 个字读者就需要停下来读，影响阅读流畅性。如果实在需要更多信息，用注释或者图例补充，不要塞进节点里。
3.3 连线规则：箭头方向、线型、标签的标准化
连线是图的血管，规则不清就会乱。diagram-design 对连线有三条硬性要求：
- 箭头方向必须明确：谁调用谁、谁依赖谁，不能有双向箭头（除非是真正的双向通信，比如 WebSocket）。如果两个系统互相调用，画两条单向箭头，不要画一条双向箭头。
- 线型区分语义：实线表示同步调用或主流程，虚线表示异步消息或异常流，点线表示可选依赖或弱依赖。这个规则要在图例里写清楚。
- 连线标签必须写动词：不要写“数据”或“请求”，要写“提交订单”、“查询库存”、“发送通知”。标签放在连线中间，不要放在箭头旁边，避免和节点名混淆。
我踩过的一个坑是：早期画图时喜欢用不同颜色的连线来区分，结果打印成黑白后完全分不清。后来改成线型区分，黑白打印也能看懂。所以颜色是辅助，线型才是主力。
3.4 图例与注释：别让读者猜
一张专业的 diagram 必须包含图例。图例里要说明：颜色含义、形状含义、线型含义、缩写含义。如果图里用了“SVC”代表服务、“DB”代表数据库，图例里必须写清楚。我见过一张图里用了“GW”，有人猜是网关，有人猜是全局，最后画图的人说那是“GateWay”的缩写。这种歧义完全可以通过图例避免。
注释的使用也有讲究。注释应该解释“为什么”，而不是“是什么”。比如你在一个判断节点旁边写“库存不足”，这是“是什么”，没必要写。但如果你写“库存不足时直接返回失败，不进入支付流程，避免无效支付”，这就是“为什么”，有价值。
4. 实操过程与核心环节实现：手把手画一张订单状态流转图
4.1 场景定义与边界确认
假设我们要画一张订单状态流转图，读者是开发和测试。边界是：从用户提交订单开始，到订单最终状态（完成或取消）结束。不涉及支付网关的内部实现，不涉及物流配送的细节。
先列出所有可能的状态：待支付、已支付、待发货、已发货、已完成、已取消、退款中、已退款。然后确认哪些状态是这张图必须包含的。如果读者是开发，那退款中和已退款可能需要包含；如果读者是运营，可能只需要看到已完成和已取消。
我最终确定的状态是：待支付、已支付、待发货、已发货、已完成、已取消。退款流程单独画一张图，避免这张图过于复杂。
4.2 状态节点布局与连线设计
布局采用从左到右的线性布局，主流程在上方，异常流程在下方。具体节点位置：
- 最左侧：待支付（起点）
- 待支付向右：已支付（触发条件：支付成功）
- 待支付向下：已取消（触发条件：超时未支付或用户取消）
- 已支付向右：待发货（触发条件：系统自动流转）
- 待发货向右：已发货（触发条件：仓库发货）
- 已发货向右：已完成（触发条件：用户确认收货）
- 已发货向下：已取消（触发条件：用户拒收）
连线标签全部用动词短语：“支付成功”、“超时未支付”、“用户取消”、“仓库发货”、“确认收货”、“用户拒收”。判断节点用菱形，放在连线中间，比如“支付是否成功”放在待支付和已支付之间。
4.3 参数计算：节点间距与画布尺寸
这一步很多人忽略，但直接影响可读性。我的经验参数是：
- 节点宽度：120px 到 160px，取决于文字长度
- 节点高度：60px 到 80px
- 水平间距：80px 到 100px
- 垂直间距：60px 到 80px
- 画布边距：上下左右各留 40px
如果节点数量超过 10 个，画布宽度会超过 1600px，这时候要考虑换行或者拆图。我通常会把画布控制在 1400px 宽以内，这样在普通笔记本屏幕上不用缩放就能看清。
注意：如果你用的是在线绘图工具，记得把导出分辨率设为 2x 或 3x，这样截图放到文档里不会模糊。
4.4 实操现场记录：从草图到成图的迭代过程
我画这张图的实际过程是这样的：
第一版：把所有状态和连线都画上去，包括退款流程。结果图太宽，打印出来字太小。放弃。
第二版：去掉退款流程，只保留主流程和取消流程。状态节点从 8 个减到 6 个，连线从 12 条减到 8 条。好多了，但“已取消”出现了两次（待支付向下、已发货向下），读者可能会困惑。
第三版：把“已取消”合并成一个节点，用两条连线分别从待支付和已发货指向它。这样节点数变成 5 个，连线 7 条。但两条线交叉了，看起来有点乱。
第四版：调整布局，把“已取消”放在最下方中间位置，待支付和已发货分别从左上和右上方指向它。交叉消失，图变得干净。
第五版：加上图例和注释，标注“超时未支付”的具体时长（比如 30 分钟），标注“用户拒收”后的库存处理逻辑。定稿。
整个过程花了大概 40 分钟，其中 30 分钟在调整布局和减少交叉。我的体会是：画图的时间主要花在“删”和“挪”上，而不是“画”上。
5. 常见问题与排查技巧实录：那些年我踩过的坑
5.1 图太复杂怎么办：拆图的三条原则
图太复杂是最高频的问题。我的拆图原则是：
- 按读者拆：给高层的图和给开发的图分开。
- 按流程阶段拆：比如下单流程、支付流程、履约流程分开。
- 按抽象层级拆：上下文图、容器图、组件图分开。
拆完之后，用一张“总览图”把它们串起来，总览图里只画大模块和它们之间的关系，不画细节。这样读者可以先看总览，再按需深入。
5.2 连线交叉太多怎么办：布局调整的四个技巧
连线交叉是视觉噪音的主要来源。四个技巧：
- 改变节点顺序：把关联紧密的节点放在一起。
- 使用正交连线：让线走直角，而不是斜线。大多数绘图工具都支持正交路由。
- 增加虚拟节点：如果两条线必须交叉，在交叉点放一个小的“跳线”符号，表示不相连。
- 换布局方向：从左到右改成从上到下，有时候交叉会自然消失。
我实测下来，正交连线加节点重排能解决 80% 的交叉问题。剩下的 20% 如果实在解决不了，就接受它，但确保交叉点清晰可辨。
5.3 团队协作时图不一致怎么办：建立视觉规范文档
团队里多人画图，最容易出现风格不一致。解决办法是建一个视觉规范文档，里面写清楚：
- 颜色词典：每种颜色代表什么
- 形状词典：每种形状代表什么
- 线型词典：每种线型代表什么
- 命名规范：节点名、连线标签的格式
- 布局规范：间距、边距、字体大小
这个文档不需要很长，一页纸就够了。但必须让所有人都能访问，并且在每次画新图之前花 2 分钟对照检查。我见过一个团队因为没做这件事，导致同一个项目的三张架构图用了三套颜色体系，评审的时候被领导问“为什么同一个系统在三张图里颜色不一样”，非常尴尬。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 图太宽，打印看不清 | 节点太多或间距太大 | 数节点数量和画布宽度 | 拆图或缩小间距 |
| 读者说看不懂 | 信息层级混乱 | 问读者“你第一眼看哪里” | 按读者分层重画 |
| 连线交叉严重 | 节点顺序不合理 | 检查节点排列 | 重排节点或换布局方向 |
| 颜色含义混淆 | 没有图例或图例不清 | 检查图例是否完整 | 补充图例并统一颜色词典 |
| 节点名有歧义 | 命名太泛或太长 | 让同事只看节点名猜含义 | 按“动词+名词”规则重命名 |
| 图与图之间不一致 | 没有视觉规范 | 对比多张图的颜色和形状 | 建立并执行视觉规范文档 |
5.5 独家避坑技巧：三个“不要”
- 不要用 3D 效果和阴影：看起来花哨，实际上降低可读性，而且打印出来一团糟。
- 不要用超过 5 种颜色：颜色越多，读者越难记住每种颜色的含义。5 种以内足够覆盖大部分场景。
- 不要在节点里写长句：节点是标签，不是段落。超过 8 个字就考虑用注释或拆成两个节点。
还有一个我个人的习惯：画完图之后，隔一天再看一遍。当天画完觉得没问题，第二天往往能发现新的问题，比如某个连线标签写错了、某个节点位置偏了。这个“隔夜检查”帮我避免了很多低级错误。
6. 工具选型与效率提升：用什么画、怎么画得快
6.1 工具选型的三个维度
选绘图工具看三个维度：协作能力、导出质量、学习成本。如果是个人用，学习成本最重要；如果是团队用，协作能力最重要。我试过很多工具，最后固定用两类：一类是在线协作型，适合团队评审；一类是本地代码型，适合版本管理和批量修改。
在线协作型的好处是多人可以同时编辑、评论、修改，适合快速迭代。本地代码型的好处是图可以像代码一样用 Git 管理，每次修改都有记录，适合长期维护的架构图。我的建议是：评审阶段用在线协作型，定稿后用本地代码型存档。
6.2 从代码生成图的思路
用代码生成图听起来很 geek，但实际用起来很香。你只需要定义节点和连线，布局引擎会自动帮你排。常用的布局算法有 dagre（适合有向无环图）、force-directed（适合关系网络）、tree（适合层级结构）。我通常用 dagre，因为它对流程图的支持最好，节点会自动从左到右排列，交叉也少。
代码生成图的另一个好处是：改起来快。比如你要把“已取消”节点从两个变成三个，只需要改一行代码，布局自动重排。手动拖拽的话，你得重新调整所有相关节点的位置。
6.3 效率提升：模板化与片段复用
如果你经常画同类型的图，建议建立自己的模板库。比如：
- 架构图模板：包含常用的外部系统、内部服务、数据库、消息队列等节点
- 流程图模板：包含开始、结束、判断、动作等标准节点
- 状态图模板：包含状态节点、转换箭头、初始和终止状态
模板不需要很复杂，关键是节点样式和连线样式已经预设好，你只需要改文字和调整位置。我自己的模板库里有 5 个模板，覆盖了 90% 的日常需求。每次画新图，先选模板，再改内容，效率至少提升一倍。
实操心得：模板不要做得太细。太细的模板会限制你的灵活性，而且维护成本高。我的模板只预设样式，不预设布局，布局每次根据内容重新排。
7. 影响范围与延展思考：diagram-design 还能用在哪里
7.1 从技术图到业务图：同一套方法论的迁移
diagram-design 的方法论不仅适用于技术架构图，也适用于业务流程图、组织架构图、用户旅程图、甚至思维导图。核心逻辑是一样的：分层、编码、布局、图例。你把这四个环节做好，任何领域的图都能画得专业。
比如画用户旅程图，分层就是“阶段层、行为层、情绪层、痛点层”；视觉编码就是“不同颜色代表不同情绪”；布局就是从左到右的时间线；图例就是说明每种颜色和形状的含义。换汤不换药。
7.2 从个人技能到团队资产：图的文化建设
一个团队如果能把 diagram-design 变成共识，收益是巨大的。会议时间会缩短，因为大家看同一张图就能对齐；文档质量会提升，因为图比文字更不容易产生歧义；新人上手会更快，因为一张好的架构图胜过十页文字说明。
我参与过的一个项目，在推行 diagram-design 三个月后，需求评审的平均时长从 90 分钟降到了 45 分钟。原因很简单：以前大家对着文字文档吵架，现在对着图讨论，争议点一目了然。图成了团队的共同语言。
7.3 从静态图到动态图：未来的可能性
静态图已经能解决大部分问题，但有些场景下动态图更有优势。比如状态流转图，如果能在图上直接模拟不同输入下的状态变化，读者理解起来会更快。再比如架构图，如果能点击某个节点展开细节，就不用拆成多张图了。
这些动态能力目前在一些专业工具里已经有了，但普及度还不高。我的建议是：先把静态图做到极致，再考虑动态。静态图都画不清楚，动态图只会更乱。
最后分享一个我自己的小习惯：每次画完一张重要的图，我会把它打印出来贴在工位上，路过的人如果停下来看，我就知道这张图成功了；如果没人看，说明还有改进空间。这个“工位测试”帮我优化了很多图，也让我养成了从读者视角审视自己作品的习惯。
