你有没有遇到过这种情况打开项目的技术文档翻到架构图那一页发现图上画的还是半年前的结构而代码里那个模块早就拆成了三个服务。新人照着老图排查线上问题折腾一晚上最后发现是图害了他。我碰过不止一次这种事儿后来才慢慢想明白一件事——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 人的团队怎么选我在不同阶段试过不同的组合很少只用一种工具。分享一个我觉得比较务实的组合方案场景推荐形态理由临时沟通任意画布工具或直接手画速度快不需要留痕架构图、模块关系图文本式工具需要进 Git需要随代码演进交互时序、状态流转文本式工具纯逻辑描述文本表达反而清晰大量节点布局很复杂的部署图画布式工具自动布局难满足多区域、多层次的视觉需求对外报告、方案展示画布式或专业设计工具需要精细控制视觉适合一次性产出关键原则是凡是生命周期超过一个迭代、需要多人共同维护的图尽量用文本式方案写进代码仓库凡是画完就交付、不进版本体系的图随便用什么画都行。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 的价值不是那张图本身而是它从一个静态的画面变成了团队对系统理解的载体。最后再分享一个小习惯每次画完一张图我都会用手机把它拍下来过几天再翻出来看。如果一眼就能看出哪里绕了、哪里乱了说明当时还有优化空间。自己审视自己的图比等别人指出问题要划算得多。