diagram-design：如何让架构图和流程图真正服务于读者决策

“diagram-design”到底在“design”什么？字面意思是图的设计，但工作里绝大多数时候，我们只是在“把已经想清楚的结构画出来”，根本谈不上设计。我过去画架构图、流程图、时序图踩过很多坑，后来慢慢总结出一套方法：图的本质是沟通工具，是用来帮人做决策的，不是用来展示“我掌握了多少信息”的。这篇就围绕这几件事展开：为什么很多图第一眼让人懵、工具和工作流怎么选、能直接用的设计规范是什么、一张图从乱到清要打磨哪些细节，以及那些没人写在文档里的坑。

如果你也经历过这样的场景——评审会上，自己花了一下午画出来的系统图投上大屏，满屏方框和连线，十几个人看了半天没人搭茬；或者流程图明明就在眼前，对方还在问“然后呢、这里到底怎么走”。这种尴尬，多半不是信息不够全，而是你只做了“画图”，没做 diagram-design。

1. 先搞清楚一件事：图是给人看的，不是给软件看的

无数人一开始画图就打开工具拖框框，拖到一半发现布局乱了，再调半小时颜色，最后得到一张“信息完整、但没人愿意看”的图。根因在于：我们以为图的价值由信息量决定，其实由信息组织方式决定。

1.1 同一个系统，两种画法，两种命运

举个具体的例子。一个订单履约系统，画法A：把网关、各个微服务、数据库表、消息队列、缓存全部放上去，类名、接口名、表名一个不落，节点三十多个，中间还有密密麻麻的双向连线。这张图不能说错，但它无法回答一个最基本的问题：“用户下单之后，数据到底经过了哪几个关键节点？”

画法B：只保留“请求进入 → 订单服务 → 库存服务 → 支付服务 → 结果回调”五个主节点，粗实线串成一条主链路；库存不足、支付失败等异常路径用红色虚线放在旁边；外部系统、数据库用浅灰色框靠边排。结果是，一个没看过代码的运营同学也能在三秒内说出“下单后会扣库存、走支付”。两幅图信息源相同，设计方式不同，效果天差地别。

这里的关键是：一张图承载的信息量是有限的，读者的注意力更是有限的。把二十个节点平均用力地摆上去，等于没有重点；把主链路从噪声中捞出来，图才真正开始工作。

1.2 画图前先问自己三个问题

动手拖第一个框之前，我建议先回答三个问题，它们决定了图的所有后续设计：

• 读者是谁？是开发、测试、架构师，还是产品、运营、客户？他们的背景决定了术语密度和抽象层级。给业务看的图，不要堆代码级命名；给开发协作的图，不要用模糊的业务黑话。
• 读者看完图之后要做什么决定？比如新同学要通过图快速摸清主路径；评审委员会要通过图判断扩展性；运维要能从图里定位故障处理位置。一张图的每一处视觉强调，都应该服务于这个决策。
• 什么信息删掉之后会影响正确理解？这就是过滤逻辑。装饰性元素、重复的箭头、进度汇报用的“美观图标”，往往都可以删掉。删除不是偷懒，是设计。

我常用一个点餐类比：图是菜单，不是后厨进货单。菜单只需要告诉客人有哪些菜、什么价格、辣不辣，不需要写今天买了多少斤土豆。如果一张图把后厨库存也画上，客人就不知道该看哪里了。

1.3 先定图的类型，再决定怎么画

另一个常见的混乱是图型不分。想表达流程，却用架构图的画法，满屏方框，判断逻辑也用方框表示，读者根本找不到分支条件；想表达系统组成，却画成流程图，让人误以为有先后顺序。图型选错，后续所有设计都是白费。

所以 diagram-design 的第一步不是打开工具，而是判断：这页内容到底应该用哪种图来表达。很多“看起来乱”的图，根子是图型选错了。

2. 工具选择：文本派、拖拽派、白板派怎么定

画图工具从来不是越贵越好。选工具的核心逻辑是：图的“生命周期”到底有多长。如果是开完会就扔的草图，用最轻的方式；如果是需要长期维护的文档图，就要选能进版本管理、能高效更新的那一类。

2.1 主流工具的三个流派

我习惯把工具分成三派：

• 文本派：用纯文本来描述节点和连线，由解析器自动生成布局。很多开发者熟悉的 dot 语法、UML 脚本、Markdown 内嵌的轻量绘图语法都属于这一类。优点是可读、可 diff、能跟着代码库做版本管理；缺点是对复杂图的手动微调能力弱，想精确控制每个节点的位置比较费劲。
• 拖拽派：所见即所得的图形化编辑器，拖一个框、画一条线，操作直观，图形库丰富。适合快速出图、对外汇报，也能做出很精致的版式；缺点是文件格式通常是私有的，不好做 diff，改动大时比重画还麻烦。
• 白板派：无限画布，手绘感强，适合头脑风暴和评审会现场共创。最大的价值是“零门槛”，谁都能上手；缺点是线条不精确，画完如果没有拍照存档，信息很容易丢。白板图通常只能算是半成品，不是交付物。

2.2 不同场景下的选择逻辑

有个判断标准可以记一下：如果这张图三个月后还要用，就先想想它会不会变。会变的图，文本格式是王炸，因为它可以被 diff，可以放在代码评审里一起看；不会变的图，用哪种都行，选最省事的。

2.3 我的选型建议和一个小原则

经历过几次“图放到文档里三个月初次被打开，发现架构早就变了”之后，我的原则变成：能进代码库的图，就不应该只存在个人的本地文件里。团队有文档维护文化的，优先文本派，因为它能跟着代码评审走；没有这种文化的，至少也要把图的源文件传到团队的在线文档空间，而不是发一份 PNG 就完了。

另外，无论选哪一派，能导出 SVG 是底线。SVG 无损缩放，在任何文档里排版都很干净；如果只能导出位图，改一次图就要重新导、重新贴，时间全耗在这种琐事上。我见过不少人因为“改图太麻烦”而放弃更新文档，最后整本文档都成了摆设，根源都是位图格式惹的祸。

3. 一套能直接抄作业的图表设计规范

画图规范听起来像是设计部门的事，但技术文档里的图同样需要。这里写一套我一直在用的硬规则，不追求艺术感，只追求“三秒能看懂”。

3.1 信息分层：主、次、辅三层

任何一张图，信息都可以分成三层：

• 主体：主链路或核心结构，必须视觉最重。用粗实线、高饱和的边框或底色来呈现。
• 次要：分支路径、可选方案、备用链路。用浅色、虚线弱化。
• 辅助：注释、指标、说明性文字。放角落或独立的“注释区”，不要进入主视觉区域。

核心规则是：同一张图中，同一视觉权重只能服务同一类信息。你给主链路的节点加了亮色阴影，就不应该再给一个备注框加同样的阴影，否则读者就会误以为备注也是主流程的一部分。视觉重量就是注意力的分配方案，随便用等于主动给读者制造混乱。

3.2 一张图能容纳多少信息

这是很多人最容易犯的错。我的经验上限是：

• 架构图：一屏内不超过 25 个主节点。超过了，就拆成系统级和模块级两张图。系统级图表达“谁和谁连”，模块级图只展开某一个子系统内部。
• 流程图：主路径尽量控制在 10 步以内；分支超过 5 个，就把其中一部分抽成子流程，用子流程引用块代替。
• 时序图：参与角色尽量不超过 6 个，否则消息线交叉得没法看。

这不是硬性规定，而是认知负荷问题。一个人工作记忆大约只能同时处理四五个信息组块，超过这个数，图就从“辅助理解的工具”变成了“需要读代码才能理解的负担”。如果一张图必须眯着眼睛找半天才知道入口在哪，它就不再是图，而是装饰画。

3.3 颜色和形状要双重编码

颜色语义最好全局统一，不要每张图换一套。我常用的约定：

• 主流程：蓝灰色系
• 成功/正常：绿色
• 异常/失败：红色或橙色
• 外部系统：灰色
• 全图颜色总数不超过 5～6 种

但有一个很容易被忽略的问题：色弱用户在人群中占比不低，黑白打印也很常见。所以不能只靠颜色区分信息类别，形状也必须同步编码。比如方框表示系统/模块，圆角方框表示服务或进程，菱形表示判断，圆柱表示数据库，泳道/容器表示环境或团队边界。就算彩色变成灰度，形状信息还在，图依然可读。

图标的使用更要注意。有些工具自带很多真实感极强的图标，快递包裹、人物头像一拖就上去，确实讨喜，但写实图形和抽象几何图形混排会迅速拉低图形的抽象层级，读者甚至会误以为图标就是系统的实际界面。要么全抽象，要么全写实，不要混着来。

3.4 文字与标注的小规则

• 字号层级：图标题 > 容器名 > 节点名 > 注释，大概对应 16 / 13 / 11 / 10 的比例，再根据实际用途缩放。
• 文字方向永远水平。不要竖排，更不要 45 度斜排，只能带来额外的阅读成本。
• 连线上的标签用动词短语：“调用 / 返回 / 写入 / 通知 / 订阅”，一个标签只表达一个动作。像“当用户已支付且库存充足时调用库存扣减接口”这种长句，不要写在线上，放到正文段落里解释。
• 命名要全局统一。同一个实体在不同图里必须叫同一个名字。最怕“订单中心”在一张图里写中文，在另一张图里写“Order Service”，读者会以为是两个系统。

这套规范看着简单，实际跑起来很有效。但真正让它发挥作用的，是把它固化成一个团队约定，而不是靠每个人自觉。

4. 从乱到清：一次架构图打磨的完整复盘

光讲原则还是容易飘，这里做一个完整的案例复盘。场景是：为某个消息推送系统画系统架构图。读者是刚入职的后端工程师 A 和一位运营同学，评审会上他们需要回答两个问题：一条推送消息从进入到触达用户，完整链路是什么？后续要接一个新的发送渠道（比如 App Push），需要改动哪些模块？

4.1 初稿的典型问题

第一版图把所有信息都塞进去了：三个上游业务（订单、营销、用户）、推送服务内部模块（接收、校验、队列、渠道转发）、两个下游渠道（邮件、短信），再加上日志、监控、失败补偿，总共二十多个节点，全部放一张图，还用了不同颜色的真实感图标和大量双向连线。

结果同事反馈很直接：看起来信息很多，但找不到从哪里开始读。我自己复盘，问题出在三点：

• 没有入口引导。整个图没有一个明确的起点，读者不知道应该从哪个节点看起。
• 信息权重平均。主链路、日志、监控在视觉上一视同仁，第一眼根本分不清重点。
• 连线过密。内部模块和两个渠道之间全部画了双向连线，叠加之后成了一团蜘蛛网，好几条线交叉穿过文字标签，根本没法读。

4.2 重构的五个步骤

我后来把重构拆成五个可执行的步骤，每一步都有明确目的：

第一步：画边界。先用最外圈的大容器标出三个区域：外部上游、推送服务内部、外部下游。这样读者一上来就建立“图分三层”的预期，入口自然就有了。

第二步：画主链路。只画“上游系统 → 接收 → 校验 → 队列 → 渠道转发 → 外部渠道 → 用户”这一条链路，用最粗的实线连接，箭头方向统一朝右或朝下。主链路清晰了，图的内容主干就立住了。

第三步：补失败分支。把“失败重试”和“死信人工处理”用虚线画在转发层右侧，“死信”再引一条细线指向辅助区的人工处理。分支存在，但没有抢走主链路的视觉权重。

第四步：降噪。日志、监控从中心区域彻底移走，放到右下角独立的小框“可观测性”，只画一条细线连到队列层，表示“这个模块产生的数据会被观测系统采集”，不再连到每一个节点。中心的连线密度立刻下降一大截。

第五步：验证。找一位完全不了解这个系统的人看图，问他：“如果订单服务要发一条短信，消息会经过哪些模块？”如果能顺着粗线说出“接收 → 校验 → 队列 → 短信渠道”，图就成功；如果答不出来，说明主链路视觉权重还不够。这一步必须做，不要自我感觉良好。

最终整理出来的结构大概是这样的示意：

[外部上游] 订单服务 营销服务 用户服务 │ HTTP [推送服务内部] 接收网关 → 校验 → 队列（按渠道分片） → 渠道转发 └───────────────┬───────────────┘ [外部下游] 邮件渠道 短信渠道 │ 用户 / 邮箱 [辅助区] 日志采集 / 监控 / 死信人工处理

这只是结构示意，实际交付时还可以加环境标签、故障处理路径，但主视觉里必须只有一条粗线贯穿全图。

4.3 这次复盘给我的启发

图不是一次画好的，而是“削”出来的：第一次画是加信息，脑海里想到什么就先放上去；第二次画是减信息，把不承担决策的节点全部移到辅助区或删掉；第三次画才是调视觉。这个“加-减-调”的循环，本质上就是 diagram-design 的完整过程。很多图之所以乱，是因为只完成了第一步就发布了。

5. 高频翻车点与让图“活下来”的日常习惯

最后聊几个我反复看到的翻车点，以及对应的解决习惯。这些坑在团队协作里尤其常见，值得单独列出来。

5.1 把图变成代码的镜像

有些图画的不是设计，而是把代码结构直接翻译成图形：一个类一个框，一个接口一条线，得到的效果和一个 IDE 里的类图没有本质区别。如果一张图只是代码的翻版，那看代码效率更高，图反而增加了理解负担。图的价值必须体现在“过滤后的关系”上，而不是“所有关系”上。如果一个模块关系复杂到无法过滤，那就不该画图，应该先重构代码。

5.2 没有图例，颜色只有自己懂

我见过一版图，作者用了七种颜色，每种代表一种环境，图例放在另一张 PPT 里，观众根本记不住。更麻烦的是，这类“加密图”往往隔两周连作者自己都要想半天。对策很简单：先把颜色语义全局统一写进团队文档，不要在单张图里发明新含义；其次，如果图里用了超过三种颜色，就在图上画出图例。白板画的图拍完照传回文档时，也要顺手把图例写清楚，否则一周后没人能看懂。

5.3 交叉线不等于高级

有些图为了体现“全”，把模块之间所有可能的连线都画了，交叉得密不透风。读者一看到这种图第一反应就是“这系统好复杂”，但这不是你的目的。处理交叉线的有效办法是聚合：把同层模块放进一个容器，容器之间只画主干连接；次要关系用编号标注、注释说明，或者干脆单独画一张局部小图。宁可主图“少一些线”，也不要让读者在交叉线里猜哪条线连到哪里。

5.4 图的一次性建设

技术圈特别常见：画图花半天，维护没人管。三个月后接口改了、模块合并了，图还安静地躺在文档里。想让图不烂在文档里，我的对策是两条：

• 把图的源文件（最好选文本格式）放进代码仓库的 docs 目录，和代码一起走版本管理。代码评审时顺手看一眼图是否需要更新，不需要追求完美，只要别过期太久。
• 给重要文档加上“图最后更新时间”字段。评审/分享前先自问：这张图还能不能回答它最初要支撑的那个问题？不能，就先更新再讲。

5.5 三秒测试和审图清单

最后分享一个我用了很久的土办法，叫三秒测试：把图交给一个不了解上下文的人，只看三秒，然后请他回答“第一眼你看到的是什么”。标准答案应该和主链路相关，比如“我先看到一条粗线从左边流到右边”“入口在左上角”。如果对方回答“好多框”“线条好乱”“看不懂”，那就说明主视觉还没确立，拿回去改。

正式发布前，我还会对照一份审图清单：

• 三秒内能找到主入口吗？
• 主链路的视觉权重是否明显大于辅助信息？
• 全图颜色是否在 6 种以内？不用颜色能否分辨结构？
• 连线标签是否都是动词短语，且不超过 8 个字？
• 图上是否有未解释的缩写或简写？
• 如果涉及多张图，同一实体的命名是否一致？

我自己多年画下来的体会是：几乎所有“图没人看”的问题，都不是画得不够精细，而是没把“主链路”和“读者决策”之间的关系想清楚。每次打开画图工具之前，先回答三个问题——给谁看、看完做什么决定、哪些信息可以不要。能回答清楚，图就已经成功了一半；剩下的，才是拖拽、配色和导出。