从混乱到可信：diagram-design 让架构图成为工程资产

两年前，我接手维护一套内部微服务文档时，发现光“业务订单流转”这个话题，四个团队就各自画了六张“架构图”，每一张的图例、箭头和分组方式都不一样。最要命的是，这些图里没有一张能回答最简单的那个问题：用户下单之后，到底会有哪些系统参与？这个经历直接催生了我对 diagram-design 这个主题的执念——不是折腾某个制图软件，而是把“画图”当成一项和写代码同等严肃的设计工作。这篇文章不聊花哨的视觉风格，只聊我是怎么定义 diagram-design 的：从沟通目标、工具选型、视觉规范，到把图表嵌进研发流程的全过程。适合后端开发、架构师、技术文档写作者，以及对“图表维护”已经受够了的任何人。

1. 先别打开画图工具：想清楚这张图是给谁读的

1.1 图表是一种“降维沟通”，不是装饰

很多人把画图当成写文档的最后一步，代码写完了，顺手画一张图放上去，觉得“有图总比没图强”。但我在多次评审中得到的真实反馈是：一张信息混乱的图，比没有图更有害。因为它给读者制造了一种“我已经看懂了”的错觉，等到深入细节才发现图里表达的东西和实际代码完全是两回事。

我的理解里，diagram-design 的第一步是承认一个事实：图表是把多维信息强行压到二维平面上。比如一张系统架构图，它同时包含组件之间的调用关系、数据流向、部署边界、异常分支、版本状态。如果你不加筛选地把这些信息全画进去，这张图就退化成一团互相交叉的线。降维沟通的核心是：你只选择当前场景里最需要传递的那一两个维度，其余信息用文字补充。

1.2 场景决定图型，而不是工具决定图型

我在给团队做内部培训时，经常问一个问题：你要画的到底是“流程”还是“结构”？这两个问题对应完全不同的图型。

流程类问题适合用流程图、时序图、状态图，读者关心的是“先做什么，再做什么，出错怎么办”；结构类问题适合用模块图、部署图、服务拓扑图，读者关心的是“有哪些组成部分，它们之间是什么关系”。

一个很常见的失误，是有人在画系统架构时把流程也硬塞进去。比如一张服务拓扑图里，既画了服务之间的依赖线，又画了“用户请求先经过 A 再到 B”的箭头，还在边上标注“如果失败则重试”。结果就是，同样的图形符号同时表达两种完全不同的语义，读者每看一条线都要猜这是调用关系还是时序顺序。

我总结了一张简单的选择表，放到项目 wiki 里，团队画图前先对号入座：

这张表不是在限制创意，而是在一开始就把“图形的语法”定下来。diagram-design 和写接口文档很像：先定协议，再填内容。

1.3 每一种连线都要能被追问

画完一张图之后，我习惯做的第一件事是随机挑一条线，问自己三个问题：这条线代表什么语义？它是同步调用还是异步消息？它是必然发生还是条件触发？

如果任何一个问题答不上来，说明这条线还没有被想清楚。这时候不应该急着把它画上去，而应该回到代码或需求里查证。这里有一个我能反复验证的经验：画图过程中的“卡壳点”，往往就是系统里设计得最模糊的地方。有一次我画一个支付回调的时序图，画到一半发现“支付成功通知”这条线我不知道是从支付网关直接到订单服务，还是先到回调网关再转发。去翻了实际代码才知道，支付网关只回调回调网关，然后由回调网关做验签和转发，通知可靠性和签名校验的责任边界完全不一样。这张图帮我发现了一个文档盲区，而这是纯文字 Review 不会暴露的。

所以，diagram-design 的一个重要原则是：每一根线条都必须经得起追问。画不下去的地方通常不是绘画技巧问题，而是系统理解问题。

2. diagram-design 的核心迁移：从画布拖拽到图表即代码

2.1 我在画布工具里踩过的三个坑

早期我用的是 draw.io 和 Visio 这一类“所见即所得”的拖拽工具。它们最大的优点是上手快，画出来的图可以直接用，布局随心所欲。但用在长期维护的技术文档里，我踩过三个非常痛的坑。

第一个坑是变更不可追踪。四个人先后编辑同一张架构图，每个人都挪动过几个框、改过几条线，但你无法通过 diff 看出这个改动是“新增了一个服务”还是“只是把框拉宽了一点”。图变成了一张不可 Review 的黑盒资产。

第二个坑是“复制粘贴式蔓延”。团队里只要有一张图画得不错，就会出现十几个副本：部署文档里一份、接口文档里一份、周报里一份，每个副本被不同人手工改过。时间一长，你根本不知道哪一份是对的。这个问题的根源是画布工具的文件很难做细粒度的版本对比，也没人愿意每次改完同步到所有副本。

第三个坑是布局感依赖个人状态。拖拽工具里，同样的内容在不同人手里画出来完全是两套风格：有人习惯从上到下画，有人从左到右；有人给每个框加一圈阴影，有人喜欢纯平面。风格不统一其实不是审美问题，而是信息表达不一致，比如“虚线”在 A 的图里代表异步调用，在 B 的图里代表弱依赖。

2.2 文本图表方案的分工与选型

后来我把主体图表全部迁移到“图表即代码”方案上。这里的“代码”不一定指编程语言，而是指用结构化的文本描述来生成图表。我目前评估过的主流工具各有各的适用场景，没有哪个能统一所有需求，实际项目中我通常会混合用。

选择逻辑很简单：如果这张图是放在接口设计文档里，说明一次调用的先后顺序，我首选 Mermaid 或 PlantUML；如果这张图是给一个数十个微服务的系统做整体拓扑，Graphviz 能帮我自动处理复杂布局；如果团队想维护一套“架构即代码”的长期资产，Structurizr 的模型层更有吸引力。diagram-design 不是绑定某个工具，而是明确工具的边界和用途。

一个文本图表的典型结构大致是这样的：

节点定义： - 外卖前端 - 订单服务 - 支付网关 - 回调服务 节点关系： - 外卖前端 -> 订单服务（HTTP） - 订单服务 -> 支付网关（发起支付） - 支付网关 -> 回调服务（异步回调） - 回调服务 -> 订单服务（更新支付状态）

文本描述的好处是，它天然强制你先把“有什么节点”和“节点怎么连”分开。很多人在画布上拖拽时不会刻意做这个分离，画着画着就乱了。

2.3 版本化与结构化 Review 的隐藏红利

图表进入代码仓库之后，最大的变化不是格式统一，而是它可以像代码一样被 Review。每次修改图表时，提交信息里写清楚“为什么改”：新增了结算服务、把同步调用改成了消息队列、删除了已下线的库存查询接口。其他同事在 Code Review 时滚动 diff 就能看出这次改动对系统拓扑的真实影响。

这里我要给一个非常具体的操作习惯：永远不要让图表文件单独变更。也就是说，如果你改了图，却没有对应的代码变更或文档变更，很可能说明你在画一个不存在的系统。反过来，如果代码变更涉及服务间的接口协议，而你却没有同步更新对应的 diagram 文件，这个 PR 就不应该被合并。把“图表是否同步”作为合并条件的一部分，能有效避免图变成永远落后的装饰品。

结构化 Review 的另一个好处，是大家可以在图表的文本注释里直接讨论，而不需要打开图形编辑器再去找对应节点。我记得有一次评审，同事在某个节点旁加了一行注释：“这个组件的健康检查没有超时时间，建议确认。”如果不是文本存储，这条评论大概率会丢在 IM 聊天记录里。

2.4 保留画布工具的四个理由

虽然我大方向上是图表即代码的拥护者，但必须诚实：现在的工作流里仍保留了少量画布工具。纯文本方案在以下四种场景里确实力不从心。

第一，快速探索和头脑风暴。白板、Excalidraw 这类工具没有语法负担，随手画一个想法、用箭头牵引思路，效率远高于文本描述。我对团队的要求是：探索阶段随便画，一旦决定进入文档，必须转成文本图表。

第二，需要精细控制视觉布局的对外图片。比如给客户做架构汇报，客户不关心你的工具链，只关心图上的信息是否一目了然。这种情况下我会在 Generate 出的图上手工调整，或者直接用画布工具重画一张干净的展示稿。

第三，贴图类、手绘风格的抽象示意。讲概念类比时，用“一张咖啡店的订单流”来做比喻，画布工具更自由。我不觉得这是需要工程约束的场景。

第四，团队里确实有人对命令行和配置文件感到强烈不适。强行逼所有人用文本图表，会激起逆反情绪，最后图也没人画了。折中的办法是：代码仓库里的正式文档用文本图表，个人的工作笔记爱用什么用什么。目的是让人愿意画图，而不是为了统一工具而统一。

3. 一张图的可读性，取决于视觉规则而不是灵感

3.1 让颜色先有语义，再被使用

很多人画图时是凭感觉选颜色的：蓝色表示服务，绿色表示数据库，黄色表示外部依赖。感觉型配色的问题在于，同一个颜色在不同图里可能代表完全不同的东西。我早期在一个项目里用过粉色代表“故障”，后来又在一张新图里用粉色代表“新功能”，结果被读者问“这系统是已经挂了还是刚上线”。

diagram-design 里的配色应该像代码里的命名一样先约定再使用。我给团队定了一套很朴素的语义色板：

这套规则不追求视觉惊艳，但保证任何一张新图递到你面前，你不需要看图例就能猜到大概含义。颜色一旦被定义为语义，就不要在同一张图里为了“好看”而临时换色。真到了不得不换色的时候，先改规则，再改图，规则和图保持一致。

3.2 方向、间距和分组的反射式设计

人眼对方向的感知非常敏感。大多数技术读者默认的读图方向是自上而下或从左到右。如果你的架构图中 80% 的箭头都指向右下，剩下的 20% 突然从下往上，读者会在心里卡一下，然后开始怀疑是不是自己漏了什么。

我处理方向的经验是：先用“主数据流”的方向确定整张图的骨架，比如用户请求从左到右经过网关、服务、数据库，那么这张图的主方向就是横向。所有分支调用、回调、异常路径都作为“次级信息”放在主链路下方或右侧，而不是喧宾夺主地穿插在主链路中间。

间距和分组其实也是在编码信息。离得近的元素会被认为是同一个集合，离得远的则被当作不同集合。与其用颜色硬区分模块，不如先把空间分好：同一业务域的服务放在一个矩形边界框内，边界框内统一用相同的底色，框和框之间保留明显的空白隔离带。这个做法在视觉心理学上叫“接近性原则”，不需要任何额外解释，读者一看就能get到分组关系。

很多工具支持子图或容器概念：在 Graphviz 里是cluster，在 PlantUML 里是package，在 Mermaid 里可以用subgraph。我建议任何超过 8 个节点的图都必须做分组，否则信息密度会迅速超过人眼处理能力。

3.3 把图例和元信息直接画进图里

技术图表的读者往往不是一次性读者。同一张图会被反复查阅，每次看的关注点都不同：这次关注服务依赖，下次关注部署边界。如果图的语义规则不明确，每次阅读都要靠猜。

解决办法是养成一个很少人做但非常有效的习惯：在图的右下角或左下角固定放一个图例区，说明本图中的箭头、线条、颜色、边框样式分别代表什么。比如：

图例： - 蓝色方框：内部服务 - 绿色圆角框：数据存储 - 橙色方框：外部依赖 - 实线箭头：同步 HTTP/HTTPS 调用 - 虚线箭头：异步消息 / 事件 - 红色描边：当前存在稳定性风险

这个图例区信息量不大，但能把一张图的“语法”固定下来。团队协同时，图例就是图表的接口文档。

另外，我还会在图的标题下方写一行元信息：这张图对应的代码目录、最近一次更新日期、维护人。原因是再过半年，回来看图的人大概率不是画图的人。有了元信息，他至少能判断这张图值不值得信任，以及找谁确认细节。

3.4 给信息密度设上限，超了就拆

我个人的经验阈值是这样的：一张技术图，如果可以独立阅读的节点超过 20 个，或者连线超过 30 条，就必须拆分。拆图的逻辑不是按面积切，而是按读者的关注点切。比如一张“订单全局架构图”，可以拆成“订单主链路时序图”“订单服务依赖图”“订单部署拓扑图”三张，分别服务不同的问题。

这个方法有点像代码设计里的单一职责原则。一张图只回答一个问题，才能保证图内的每个元素都在为这个问题服务。如果舍不得拆，就会看到后来的人在这张图上继续堆节点，堆到最后，图变成了没人能读懂的“地图炮”。

4. 一次完整的架构图设计过程：从零梳理订单核心链路

4.1 先收集事实，别急着连线

很多人在画图时倒过来：先打开工具，拉个框写“用户”，再拉个框写“订单系统”，然后开始连线，一边连一边想还缺什么。这样画出来的图往往缺节点，因为思维顺序是顺向的，容易漏掉边界情况和反向调用。

我的处理顺序是先按住自己，用纯文本把事实列全。以一张订单服务拓扑图为例，我会先列出所有参与者：

前端：外卖小程序/H5 入口：Nginx 网关 核心服务：订单服务、支付服务、库存服务、积分服务、消息中心 数据存储：MySQL（订单库）、Redis（缓存）、MQ（订单消息） 外部依赖：微信支付、地图定位服务、短信服务商

这个阶段不关心“画得漂不漂亮”，只关心“有没有遗漏”。信息来源包括实际代码目录、接口清单、部署配置、以及线上监控里的服务调用关系。有条件的话，宁可跑一遍 trace，也别只凭记忆画。

4.2 第一版必然是一堆乱糟糟的方框

把节点列完后，我通常会生成一版“平铺图”：所有节点都在一个平面上，不分组、不排序，只用最原始的线条表达调用关系。这一版一定很难看，但它有一个重要作用：暴露出系统的真实复杂度。

平铺图里最常见的问题是“跨层级依赖”和“网状调用”。比如前端直接调用了订单服务，订单服务又直接查了用户服务，用户服务还反向调了订单服务查订单状态，这些在平铺图里会形成交叉线。看到交叉线不要急着重新布局，而是先问自己：这些依赖是不是设计上就是合理的？有些交叉是架构腐化的信号。

我第一次给一个老项目画服务拓扑时，平铺图里出现了超过 30 条交叉线。我顺着每一条交叉线去翻代码，发现有两个服务存在循环依赖：订单服务调用库存服务，库存服务在超卖回滚时又反过来调用订单服务的接口修改状态。这个循环在图上一目了然，但在代码评审里被忽略了很久。

4.3 用“边界”而不是“颜色”做分组

纠正了不合理的依赖之后，再来处理平铺图的混乱。我的分组原则是：边界框优先于颜色，分层优先于位置。

对于订单系统，我分了三个边界：

• 接入层：前端、Nginx、网关
• 业务层：订单、支付、库存、积分、消息
• 依赖层：MySQL、Redis、MQ、微信支付、短信服务

同一个边界框内部的节点是允许存在依赖关系的，边界框之间的箭头表示跨层访问。跨边界的线条越少，说明系统分层越清晰。很自然的，当我把全部节点装进这三个框后，图面立刻干净了，因为绝大多数调用都发生在业务层内部，跨边界的只有几条骨干链路。

这个做法的本质是用“容器边界”替代“颜色区分”。颜色只能让人在视觉上归类，但边界框还能限制节点的活动范围，思路更接近代码里的命名空间。

4.4 重新定义箭头的含义，而不是全部画实线

确定分组后，下一步是重新审视每一条连线的语义。我要求每条线要么是“同步调用”，要么是“异步消息”，并且箭头样式必须一致：实线代表同步，虚线代表异步。

平铺图阶段有些线画的是“订单服务 -> 消息中心”，这其实是发消息，不是调用接口。如果全画实线箭头，读者会误以为订单服务在同步等待消息中心返回。改成虚线后，语义立刻清晰了。

支付回调这条也非常典型。支付网关异步调用回调服务，回调服务再主动查一次订单服务，或者通过 MQ 通知订单服务。线型不同，排查问题时的思路完全不同。这张图在 QPS 不高的时候看不出区别，但一旦出现回调延迟，虚线还是实线决定了你是先去查 API 超时还是先去查消费堆积。

4.5 加一层“风险标注”，让图具备可操作性

架构图不只是现状的映射，还应该是改进方向的输入。所以我会在图上额外标出风险点：不稳定依赖用红色描边，存在循环依赖的节点在图上注释，以及对账补单的关键路径单独打星号。

比如，订单服务依赖库存服务做库存预占，这个调用是同步的。一旦库存服务变慢，订单服务的线程池会被占满，进而拖垮整个下单入口。我在图上把这条线加粗并标成红色，旁边备注“库存服务超时未设置，存在级联故障风险”。这张图后来被拿到架构评审会上，直接推动了超时时间和熔断阈值的配置优化。

风险标注让图表从“记录现状”变成“指导行动”。否则，图只是给大家一个虚假的安全感，看过之后一切照旧。

4.6 渲染之后的“可信度检查清单”

最后一步是在渲染完成的图上做一次清单检查。我先贴团队现在用的检查项：

• 每个节点是否都有真实的代码或配置文件对应？没有的话是不是纯概念节点？
• 每条线上是否有明确的协议或载体？对应的接口路径或消息 Topic 是否能在代码里搜到？
• 图里的所有服务是否都还在线上运行？有没有已下线但没删除的僵尸节点？
• 如果读者只花 15 秒看这张图，他能不能说出系统由哪几个核心部分组成？
• 如果读者进一步花 5 分钟对照图去查日志，图的描述是否与日志行为一致？

这份清单不是为了找茬，而是为了防止“把图画得很完整，但和真实系统没关系”的情况。我见过太多“理论上很完美”的图，对着监控一看根本不是那么回事。图的最高原则是诚实。

5. 把图表嵌进工程流程：评审、版本、发布与自动化

5.1 图表进入 Git 仓库的目录规划

我建议在仓库中专门建一个docs/diagrams目录，按照图的用途而不是系统模块来组织。用途维度比模块维度更稳定，因为系统模块会不停重命名和拆分，而用途（如“订单主链路”“部署环境”“接口时序”）通常保持稳定。

一个经过几个项目验证的目录结构大致是：

docs/diagrams/ ├── architecture/ │ ├── order-system-overview.dot │ └── payment-flow.puml ├── sequence/ │ ├── create-order.puml │ └── refund-callback.puml ├── deployment/ │ ├── staging.dot │ └── production.dot └── README.md

README 里写清楚每张图对应的代码模块、维护负责人、以及“改代码必改图”的约定。这个目录结构本身也是一种 diagram-design 的实践：文档的结构和代码的结构保持对称，读者想找哪张图，凭直觉就能找到。

5.2 图表评审关注什么：语义优先于绘图技巧

图表 Review 很容易变成“你觉得这个颜色不好看”之类的闲聊。为了避免低效，我在 PR 模板里列了四个固定问题：

• 这次改动是否引入了新的节点或关系？如果有，是否与实际代码对应？
• 是否有节点或关系被删除？这些删除是否和代码下线或重构保持一致？
• 改动会不会影响其他文档的引用？如果会，是否同步更新？
• 图的语义是否因为本次改动变得模糊？比如箭头数量是否超过读者短时记忆的极限，信息密度是否过高？

这四问把图表评审从主观审美拉回到事实核对。如果 PR 里只有绘图修改，没有配套代码或文字说明，我会直接打回，因为那往往意味着有人在手工“美化”一张和现状脱节的图。

5.3 与文档流水线的集成方式

文本图表的另一个好处是可以被流水线自动处理。我们在 CI 里做了一个很轻量的步骤：把指定目录下所有图源文件渲染成 SVG 或 PNG，再上传到静态文档站。这样，Markdown 里引用的是 SVG 文件，而不是源代码本身。任何人提交了新的.puml或.dot文件，文档站会自动更新。

对于复杂度冲突，我会把图拆成多个小图，让每张图在 Markdown 中独立呈现。比如订单详情页的时序图拆成“下单时序”和“退款时序”两张，中间用文字过渡指引。阅读体验会比一张巨型图好很多。

还有一个小技巧：在每张渲染图的底部用脚本自动生成一行版本信息：

生成时间：2026-02-18 14:23 源文件：docs/diagrams/sequence/create-order.puml

这行信息能避免“读者看到一张旧图还以为是最新的”这种尴尬。版本信息是图表可信度的护栏。

5.4 半自动化的边界：别让生成脚本取代思考

技术圈里有一股“万物自动化”的风气，似乎不自动生成图就不够高级。我的态度是：机器可以帮你把数据变成图，但解决不了“这张图该表达什么”的问题。

我在某些监控大屏上尝试过直接从指标元数据生成拓扑图，说实话，对于“发现新服务上线”“发现调用关系异常”这类异常检测，自动图很有价值。但它生成的图通常没有经过语义筛选和风险标注，信息密度极不均匀，不适合作为架构评审的输入。所以我的结论是：用脚本生成数据图，用人工维护逻辑图和架构图。生成式图表的定位是辅助发现，而不是替代人类的 diagram-design。

6. 维护几年后的真心话

6.1 图表不是洋葱，越分层越没人看

C4 模型提出分层视角是有价值的，但很多团队把它理解成“必须画四层图”，于是一张系统上下文图、一张容器图、几张组件图，叠起来一大本，最后除了画图的人自己，谁也没看完过。

我现在的原则是：按需分层，而不是按模型分层。如果团队只关心服务部署在哪里、谁调用谁，两张图就够了。只有当你需要深入某个容器的内部结构时，才为它单独画一张组件图。为分层而分层的架构图，本质上是在用形式感掩盖思考的懒惰。

6.2 删除不用的图，比画新图更重要

图表和代码一样，是有维护成本的。我在仓库里看到超过一年没有更新、也没有链接指向的图时，会毫不犹豫地删除。删除前我会做一次确认：图描述的系统模块是否还在？图中涉及的接口是否还存在？有没有其他文档链接到这张图？

如果没有，说明它已经成了噪音。删掉一张过期的图表，不会让团队损失信息，只会让剩下的人少一份“这张图可能是可信的”误判。我常说，diagram-design 不只是怎么画图，还包括怎么让图保持生命力，而生命力的一部分，就是适时地让它消失。

6.3 一张诚实但粗糙的图，胜过一张精致但说谎的图

这几年我最大的体会是：技术图表的最终价值是帮助团队建立一个共享的心理模型。这个模型应该和真实系统的行为一致，否则图越漂亮，危害越大。

有不少非常精美的架构图，颜色统一、箭头整齐、排版对称，但仔细核对后会发现，它缺少实际部署结构、没有标出单点故障，甚至连服务名称都是错的。这种图的存在比不画图更糟糕，因为所有人都基于一个错误的模型做决策。反过来说，一张手绘的、带涂改痕迹的草图，只要关键节点和关键链路是对的，它对团队协作的贡献远大于一张空有其表的成品图。

所以我把 diagram-design 这件事落地的核心原则很简单：先保证图说真话，再想办法让它好看。团队协作里，没有比“可信”更重要的审美标准。