你有没有遇到过这种情况：打开项目的技术文档，翻到架构图那一页，发现图上画的还是半年前的结构，而代码里那个模块早就拆成了三个服务。新人照着老图排查线上问题，折腾一晚上，最后发现是图害了他。我碰过不止一次这种事儿，后来才慢慢想明白一件事——diagram-design真正要解决的，从来都不是"把图画得好看"，而是"怎么让一张图在项目持续演进的过程中长期保持可用，并且让人愿意持续维护它"。

这篇文章不是软件教程，也不是设计理论课。我想从一个做项目、做产品、做系统的人的角度，聊聊我这些年对 diagram-design 的完整思考：为什么大多数项目里的图会烂掉，怎么选工具才不会被工具绑架，画图之前应该先做什么，以及怎么让图从"一次性的交付物"变成"跟代码一起演进的活文档"。如果你也负责某个系统的设计文档、架构说明，或者经常要给团队画流程图、时序图、部署图，这篇文章应该能在一些关键节点上帮你避开我踩过的坑。

1. 图表设计不只是画图：先想清楚你在这张图上押了什么注

我一直觉得，diagram-design 最大的误区就是把它理解成"用工具画图"。工具只是最后落笔的那一下，真正花时间的应该是落笔之前的思考。一张图本质上是一种空间化的信息表达，你把本来按时间顺序、按逻辑关系展开的信息，压缩到一个二维平面里。这个压缩过程本身，就是设计。

1.1 三种不同的图，三种完全不同的生命周期

我习惯先把图分成三类，因为它们的生命周期和维护策略完全不一样。

第一类是临时沟通图。比如你跟同事解释某个模块的数据流向，随手在白板上画两笔，或者用画图软件拉几个框。这类图的寿命可能只有五分钟，画完用完就扔。对这类图谈设计规范、谈版本管理，纯属浪费时间，能快速表达清楚就够了。

第二类是项目记录图。这类图会进入技术文档、设计评审材料，跟着项目走几个月甚至几年。它需要一定的规范性，因为它会被多个人阅读，会被讨论，会在项目演进过程中被反复修订。

第三类是系统分析图。这类图服务于架构决策、容量规划、故障排查，你画它是为了推演某种方案成不成立。比如画一张数据流图，看看某个环节的瓶颈在哪。这类图最不需要好看，但最需要准确，而且往往要覆盖异常路径，不能只画快乐路径。

很多团队的图之所以烂掉，就是因为他们用画"临时沟通图"的心态去画"项目记录图"，或者用画"系统分析图"的复杂度去画"临时沟通图"，根本没有考虑这张图的预期寿命。

1.2 决定成败的不是美术功底，是"阅读路径"设计

在这里我要说一个可能反直觉的结论：一张好的技术图，跟美术功底基本没有关系。见过太多画得花里胡哨、有渐变阴影和 3D 效果的架构图，读者一眼看过去完全不知道该往哪儿看。问题就出在作者没有设计阅读路径。

什么叫阅读路径？就是读者的视线在这张图上该按什么顺序移动。好的图，第一眼应该看到的是最重要的那个模块，然后视线自然地沿着主流程走，最后才去看细节。这就像地铁线路图，它不会把每个站附近的餐厅、商场都画上去，它只画线路和换乘点，但你一眼就能规划出一条从家到机场的路线。

设计阅读路径的一个实用方法是：先问自己"如果读者只能花五秒钟看这张图，我希望他带走什么信息"，把这个信息放到图的视觉中心；然后再问"如果读者愿意花三十秒，我希望他看到什么"，这部分放在第二层级；最后才是那些"可能有人关心的细节"，压缩到图表的边角或附录里。

我见过一张做得不错的订单系统架构图，最中央只有两个框：订单服务和支付网关，一条粗线连着它们，标注"核心交易链路"。周边所有的服务、缓存、消息队列都用很淡的颜色画在旁边，字体也小一号。所有人看到这张图的第一反应都是先看中间那条链路，这就是阅读路径设计成功了。

2. 工具选型不是挑软件，是挑"信息维护方式"

很多人选图表工具的时候，比的是哪个画出来好看、哪个拖拽更流畅，但我觉得应该比的是另一个维度：这个工具用什么方式维护信息。大概分两派：文本式和画布式，中间还有一些混合形态。

2.1 文本式工具：把图写进代码仓库

文本式工具的代表思路是：用一段结构化文本描述节点和连线，然后工具把文本渲染成图。这类工具的典型特点是图源文件是一个文本文件，可以放进 Git 仓库，可以做代码评审，可以 diff。

文本式最大的好处是"图跟着代码走"。你改了代码，顺便改一下图源文件，提交的 MR 里就同时带着代码变更和图变更，评审人能看到图是怎么演进的。另一个隐藏好处是文本不怕脏，不怕坏，Git 就是天然的历史回滚机制，改错了随时 revert。

代价也很明显：排版自由度低。你很难精确控制某个框的坐标，所有布局都是算法自动算出来的。遇到复杂的部署关系图，自动布局容易绕线，看起来不如手排的舒服。

2.2 画布式工具：极致自由与隐性成本

画布式工具就是大家熟悉的那些拖拽式产品，支持像素级调整位置，想放哪儿放哪儿，想画多漂亮画多漂亮。这类工具的上手门槛低，任何人双击就能画一个框。

但这类工具有一个隐性成本：你的图存在它自己的服务器或本地文件里，跟代码仓库是两套体系。图改了，没有 diff，没有 review，没有人知道上一版长什么样。我见过最典型的场景是：某个团队用画布工具画了一张很完整的架构图，后来某个同事为了画自己的部分，把其他人的模块挪了个位置，保存。一个月后另一个模块的负责人发现图变了，但他完全不知道是谁改的、什么时候改的、为什么改。从那以后，那张图就再也没有人敢动了。

2.3 我的选型经验：规模小于 10 人的团队怎么选

我在不同阶段试过不同的组合，很少只用一种工具。分享一个我觉得比较务实的组合方案：

关键原则是：凡是生命周期超过一个迭代、需要多人共同维护的图，尽量用文本式方案写进代码仓库；凡是画完就交付、不进版本体系的图，随便用什么画都行。

2.4 一个小团队的实操配置

我现在自己维护开源项目或者内部系统的时候，常用组合是：一个文本式工具作为主方案，用于所有"需要长期维护的图"；一个轻量画布工具作为辅助，用于"pass 掉想法后要进正式文档做精细化排版"的图。主方案的图源文件放在项目仓库的 docs 目录下，并且把生成的图片也提交进去，这样 Git 平台上可以直接预览到最新版。

如果你问我有没有做到"一套工具打天下"，我的答案是做不到。每种工具的定位不同，强行统一某种工具，必然会在某个场景上增加大量额外成本。

3. 从一个模糊想法到一张能用的架构图：我的实操流程

这几年我画图严格走一套流程，每步都不跳。这套流程不是从哪个教科书上看来的，是吃了不少亏之后总结出来的。

3.1 第一步：不碰画布，先写一份纯文本的信息清单

很多人画图失败，不是因为不会用工具，而是因为脑子里根本没有想清楚"这张图里到底有哪些东西"。我给自己定了一条硬规矩：打开画布之前，先打开文本编辑器，回答以下几个问题：

• 这张图里有哪些实体？实体就是服务、模块、系统、角色、设备之类的东西。
• 实体之间存在什么关系？是调用、依赖、包含、连接、发送消息，还是别的什么。
• 这些关系和实体里，哪些是这张图的核心？哪些只是上下文背景？

用最朴素的方式回答，比如写一个这样的清单：

用户端（PC Web） -> 网关服务 用户端（移动 App） -> 网关服务 网关服务 -> 订单服务 订单服务 -> 库存服务 订单服务 -> 支付服务（外部） 订单服务 -> 消息队列 库存服务 -> 数据库

写完之后检查一遍：这个清单里有没有冗余实体？如果有个实体跟主线毫无关系，删掉。接着再想一个问题：如果读者只关心"下单链路"，那么订单服务、支付服务要画重点，其他都可以弱化。

这一步很多人觉得没必要，直接打开画布就能画。但我的经验是，先写文本再画图，速度至少快一倍，而且画出来的图结构清晰得多。因为你已经提前完成了逻辑梳理，画图只是把文本翻译成图形。

3.2 第二步：用"分层"代替"排版"来解决布局问题

布局乱，不是排版技巧的问题，往往是分层没做好。我的做法是：先把所有实体按逻辑分成层，每层一个横向条带，然后从左到右或从下到上按依赖关系排列。

以我之前画过的某块业务为例，我会分四层：

• 接入层：Web 页面、App 客户端、OpenAPI 对端系统。
• 网关层：统一鉴权、路由分发。
• 业务层：订单、库存、支付、用户。
• 数据层：数据库、缓存、消息队列。

画的时候，接入层在最上面，往下依次是网关层、业务层、数据层。主流程的边用实线加粗，次要依赖用虚线。这样做出来的图，就算节点再多，也不会让人觉得像一团乱麻。

分层的核心逻辑不是技术栈分层，而是"职责边界"。同一技术栈里可能同时包含不同职责的模块，硬把它们放一起画反而误导读者。

3.3 第三步：定一套只有三个角色的视觉规范

视觉规范不需要很复杂，越简单的规范越容易执行。我给自己定了一个"三色规范"：

• 一种颜色表示"本系统内部模块"，我用冷色系，比如深蓝。
• 一种颜色表示"外部系统或第三方依赖"，我用暖色系，比如橙红。
• 一种颜色表示"被动数据存储"（数据库、缓存、对象存储），我用灰色。

然后线的类型也就三种：实线表示"强依赖的同步调用"，虚线表示"异步消息或事件通知"，点线表示"配置管理、监听或非核心链路"。

这套规范我已经用了很久。它能让你在一张不算太小的图里快速判断"这个系统的边界在哪""哪些环节是异步的"。如果一上来就追求多重颜色、不同线型花式表达，最后一定会失控——因为项目中任何人画的段落，色彩语言都对不上。

3.4 第四步：与代码评审同节奏的图表评审

这一步是我最想强调的。图画完不是终点，它应该进入评审环节，像代码一样被 review。操作方式很简单：在架构评审或者代码评审的时候，把图源文件的变更内容贴在评审描述里，让评审人看到"这张图哪里改了，为什么改"。

我见过很多团队有图，但图从来没被评过。结果就是画图的人自己觉得理所当然，看得人一头雾水：这个框为什么存在？这条线为什么是虚线？两个模块之间为什么没有缓存？如果图参与了评审，这些问题在合入之前就暴露了。

我现在自己每次改图都会在 MR 描述里附上图的 diffs 截图，用一两句话说明改动意图。比如"网关层新增限流组件，因为上游流量波动太大，需要在入口做保护"。这样做以后，团队里其他人对图的理解程度明显提升了。

4. 四个真实项目里最常见的翻车现场与补救方式

这一部分是我最想写的，因为每一条都是我真实踩过坑之后才意识到的。希望你看完能少走一些弯路。

4.1 翻车现场一：把架构图画成了架构全景地图

某一次，我在一个中型项目里做技术复盘，翻出团队之前画的一张"系统全景图"。那张图大概有两百多个节点，每个微服务、每个数据库实例、每个消息队列主题全都画上去了，还按机房分区。坦率说，画得很认真，但完全没法用。任何人打开它，第一反应是想找到自己关心的模块，然后在一堆节点里迷失方向。

问题出在哪？画图的人没有做"信息裁剪"。一张图的承载能力是有限的，你什么都想画，最后就是什么都看不清。这就像把整个城市的每栋楼都画在地图上，你反而找不到去机场的路。地图的正确画法是有意省略，只保留对你目标有意义的信息。

补救方式有两种。第一，强制分层：大图保留为主干抽象图，只画核心链路和关键边界，把每个子系统的内部图画成单独的图，再用链接互相跳转。第二，通过颜色和透明度做信息权重：核心节点的颜色饱和度最高，边缘节点降低透明度，让读者的注意力自动聚焦。

4.2 翻车现场二：颜色先上，语义后补

有些团队画图的时候喜欢先给节点填充漂亮的颜色，觉得这样"好看""专业"。但过段时间有人问：为什么这个模块是绿色的，那个是蓝色的？答不上来。颜色本身没有语义，纯装饰性的颜色在技术上就是噪音。

我后来定的规矩是：每个颜色必须有定义。比如在图的右上角固定放一个图例，说明"深蓝=内部服务，橙红=外部依赖，灰色=存储"。哪怕是三个人看的内部图，也放。这样任何新加入的成员都能迅速读懂，也不用频繁口头解释。

另外一个跟颜色相关的坑是色弱问题。我自己身边就有色弱同事，红绿对比的线条和节点在他眼里几乎没有区别。所以我对无色彩表达能力的要求更高：关键信息不要只靠颜色区分，还要结合线型、字体粗细和节点形状，让图在有色彩障碍的读者那里也不会失效。

4.3 翻车现场三：只画主流程，异常路径全失踪

这是我见过最多的一个问题。大部分人手绘流程图、时序图的时候，都会不由自主地只画"正常路径"：用户下单，订单创建，支付成功，库存扣减，结束。没有人画"支付超时怎么办""库存扣减失败怎么办""重复回调怎么办"。

但真实系统的复杂度恰恰藏在异常路径里。数据不一致、故障恢复、边界条件，这些才是线上事故的高发区。只画主流程的图，在排查故障时几乎没有价值——因为故障时走的全是异常路径。

我现在的习惯是：画一张图之前，先写一份"路径清单"：

• 主路径：正常请求如何流转。
• 分支路径：不同条件下如何分流。
• 异常路径：超时、失败、重试、补偿怎么走。

画图的时候，主路径用实线粗体，异常路径用虚线细体，并且给每个异常路径编号，编号对应文字的详细说明，放在图的下方注释区。这样一来，平时看着像一张很干净的架构图，真出事的时候，那张细致标注的注释区就成了排查故障的重要参考。

4.4 翻车现场四：图上线的那一天，就是它过期的第一天

这个翻车现场估计所有带过图的人都深有体会。画图花了两天，后面半年没人碰它。系统加了新模块，没人更新图；某个依赖服务下线了，也没人更新图。半年之后再打开，图反而成了阻碍理解的障碍。

我复盘过为什么会这样，结论是：因为这张图是"一次性交付物"，它的生命周期在保存的那一刻就结束了。没有人会为一张跟代码分离、且无法自动关联的图持续投入维护精力。

补救方式就是前面我反复强调的：让图跟代码同源、同变更、同评审。图源文件进代码仓库，改动随代码一起提交；架构评审时先看图变更，图不过，变更不进。只用这种方式，图才有可能跟上系统的演进。

如下表所示，有些关键症状一眼就能对应上原因和行动：

5. 让图表进入自动维护循环：从一次性交付到持续演进

如果你已经决定把图纳入工程体系，那接下来就值得思考一件事：怎么让更新图的成本降到足够低，低到团队愿意为此付出一点点时间，而不会觉得是在做额外的工作。

5.1 用注册表驱动的自动更新

一个可行的思路是建立一个"架构注册表"。核心思路是：把系统中的所有服务、依赖关系、数据存储定义成一份结构化清单，然后用一个脚本把清单渲染成图。代码在项目仓库里维护，服务上线时注册一条记录，服务下线时删除一条记录，图随之自动变化。

我用文字描述一下注册表的结构，大概是这样：

service order-service: type: internal depends_on: [payment-gateway, inventory-service] async_emit: [order-created-event] storage: [order-db] storage order-db: type: database critical: true service payment-gateway: type: external

有了这个清单，画图工具只需要做一件事：读清单，生成图。这个方案的好处是，维护图的成本变成了维护一条条简单的注册记录，而且这份记录本身还是一项很有价值的元数据，后续做容量规划、故障影响分析都能用。

如果你觉得这个方案对你来说太重，也可以退一步：只在你每次改动代码的时候，顺手改对应的那部分图源文件，并在提交记录里写明 "docs: update architecture diagram"。重点是保持"图跟代码同步变更"的习惯，而不是等某一天专门花时间去同步。

5.2 把图表变更当成代码变更来审查

我还想强调另一个习惯：图参与评审。很多团队有架构评审、代码评审，但很少有"图评审"。我建议你下次在评审 MR 的时候，顺便看看这个 MR 有没有更新相关的图表。如果没有，说明改代码的人漏掉了，你可以在评审意见里补一句："涉及网关层变更，建议同步更新架构图。"

等到团队形成这个默契后，图就不容易过期了。因为你不需要单独安排一个"维护图"的任务批次，而是让它在每一次代码变更中自然发生。久而久之，文档里那部分图，会成为团队最快的技术索引。

我自己在实际项目里真正受益的瞬间，是某次线上故障复盘时，团队打开架构图，发现异常路径说明区里明确写着"支付超时后，订单服务发出补偿事件，由补偿器在 30 秒后重新查询支付状态"。当时所有人都在安静地看这张图，没有人争辩流程是谁定义的，因为图的作者已经把逻辑记录下来并经过了评审。那一刻我意识到，diagram-design 的价值，不是那张图本身，而是它从一个静态的画面，变成了团队对系统理解的载体。

最后再分享一个小习惯：每次画完一张图，我都会用手机把它拍下来，过几天再翻出来看。如果一眼就能看出哪里绕了、哪里乱了，说明当时还有优化空间。自己审视自己的图，比等别人指出问题要划算得多。