diagram-design：从草图到系统，技术方案图设计方法论

1. 从一张草图到一套系统：diagram-design 到底在解决什么问题

第一次看到 “diagram-design” 这个标题，很多人会以为它只是教你怎么画流程图、时序图或者架构图。但真正做过技术方案、写过设计文档、跟产品运营吵过架的人会明白，图只是表象，背后真正要解决的是信息如何被准确、高效、低损耗地传递。我做了十多年一线开发和技术方案，见过太多团队把图画得花里胡哨，结果评审会上没人看得懂；也见过一张极简草图，五分钟就让所有人对齐了方案。diagram-design 的核心，就是把这件“看起来靠感觉”的事情，拆成一套可复用的设计系统。

它适合谁？如果你是需要写技术方案的后端、前端、架构师，或者是需要把复杂业务逻辑讲清楚的产品经理、项目经理，甚至是需要给客户做方案汇报的售前同学，这套东西都能直接用。它不挑工具，不依赖某个特定软件，核心是一套思考框架和落地方法。你可以用它在白板上画草图，也可以用代码生成图表，甚至用设计工具做高保真架构图。关键是，图背后的逻辑要立得住。

我先把结论放在前面：diagram-design 不是“画图技巧合集”，而是一套从信息分层、视觉编码到协作评审的完整工作流。它要解决的问题包括：图太复杂没人看、图太简单说不清、图更新不及时导致文档过期、不同角色对同一张图理解不一致。这四个问题，几乎每个技术团队都踩过。接下来我会从设计思路、核心细节、实操过程、常见问题四个维度，把这套方法拆开讲透。

2. 整体设计思路：为什么你的图总是“画了等于没画”

2.1 信息分层：先决定“不画什么”，再决定“画什么”

很多人画图的第一反应是打开工具，拖几个框，连几条线。但 diagram-design 的第一步恰恰相反：先做减法。一张图能承载的信息量是有限的，心理学里有个粗略的经验值，人在一次浏览中能同时处理的视觉元素大约在 7±2 个。你硬塞 30 个节点进去，读者的大脑直接宕机。

我的做法是先把要表达的信息分成三层：

• 核心层：这张图必须让读者记住的 1 到 3 个关键点。比如“订单服务通过消息队列异步通知库存服务”，这就是核心。
• 支撑层：为了理解核心层而必须存在的上下文。比如订单服务、库存服务、消息队列这三个节点。
• 细节层：可以放到附录、备注或者第二张图里的内容。比如消息队列的具体型号、重试策略、死信队列配置。

实操中，我会拿一张纸，先把所有想画的东西列出来，然后强制自己划掉细节层。划掉的内容不是丢掉，而是放到图下方的“补充说明”里，或者单独出一张“部署细节图”。这样主图永远保持清爽，读者第一眼就能抓住重点。

注意：信息分层不是一次性的。评审时如果发现有人反复问某个细节，说明这个细节应该被提升到支撑层甚至核心层。图的层次是跟着沟通效果迭代的。

2.2 视觉编码：颜色、形状、线条都是有“语法”的

diagram-design 里最容易被忽视但又最影响理解效率的，是视觉编码的一致性。我见过一张图里，蓝色既表示“数据库”又表示“外部系统”，虚线既表示“异步调用”又表示“可选依赖”。读者每看一个元素都要重新猜含义，认知负担直接翻倍。

我的经验是建立一套最小视觉语法，并且在整个文档甚至整个团队里保持一致。下面这张表是我常用的编码规则，你可以直接抄：

这套规则不需要多复杂，关键是团队内达成共识。我们团队曾经因为“虚线到底表示异步还是表示弱依赖”吵了半小时，后来直接把规则写进文档模板，新同学入职第一周就要过一遍。从那以后，评审会上关于图本身的争论少了至少一半。

2.3 工具选型：别让工具绑架你的表达

diagram-design 不绑定工具，但不同场景下工具的选择确实影响效率。我按使用场景分三类：

• 白板/草图阶段：纸笔或者白板最好。这个阶段目标是快速对齐，不要纠结美观。我习惯用不同颜色的便利贴代表不同服务，随时可以撕下来重排。
• 文档/评审阶段：推荐用代码生成图表的工具，比如 PlantUML、Mermaid 或者 Structurizr。好处是图可以跟代码一起进版本管理，改起来快，而且风格统一。坏处是学习成本，但一次投入长期受益。
• 汇报/对外阶段：可以用设计工具做高保真图，但前提是前面的逻辑已经跑通了。我见过太多人直接跳到这一步，结果图很漂亮，逻辑一塌糊涂。

提示：如果你团队还在用截图贴文档的方式，强烈建议换成代码生成。截图最大的问题是无法追溯、无法 diff、无法批量修改。代码生成的图，改一行文本就能更新，评审时直接看 diff 就行。

3. 核心细节解析：一张好图的五个关键决策点

3.1 粒度控制：一张图只讲一件事

这是我最想强调的一点。很多技术方案文档里，一张图试图同时表达业务架构、技术架构、部署架构、数据流。结果就是每个维度都画了一点，但每个维度都说不清。diagram-design 的原则是：一张图只回答一个问题。

比如“订单系统重构”这个项目，至少需要三张图：

1. 业务流程图：回答“用户下单后发生了什么”，面向产品和运营。
2. 服务依赖图：回答“订单服务依赖了哪些下游”，面向开发和架构评审。
3. 部署拓扑图：回答“这些服务部署在哪些节点上”，面向运维和 SRE。

每张图的读者不同，粒度自然不同。业务流程图可以粗到只画“下单-支付-履约”三个框，服务依赖图要细到具体接口和中间件，部署拓扑图要标清楚机房、集群、副本数。如果你把这三张图合并成一张，读者会疯掉。

3.2 布局方向：从左到右还是从上到下，有讲究

布局方向直接影响阅读顺序。我的经验是：

• 时间顺序或调用链：从左到右。比如用户请求经过网关、服务 A、服务 B、数据库，横向排列最符合直觉。
• 层级关系：从上到下。比如接入层、逻辑层、存储层，纵向排列能体现上下级依赖。
• 网络拓扑：按实际地理或逻辑区域分组。比如同机房的服务放一起，跨机房用虚线框隔开。

有个细节很多人忽略：箭头方向要统一。如果一张图里有的箭头从左到右，有的从右到左，读者会不自觉地来回扫视，效率很低。我通常强制所有主流程箭头从左到右，只有回调和反向依赖才用反向箭头，并且用不同颜色标出来。

3.3 命名规范：节点名字决定图的可读性

节点命名是 diagram-design 里最“不起眼”但最影响体验的部分。我见过太多图里写着“ServiceA”、“Module1”、“DB”，读者根本不知道这是什么。好的命名应该满足三个条件：

• 见名知意：order-service比svc-a好，inventory-db比db1好。
• 长度可控：太长会撑爆框，太短看不懂。我的经验是中文 4 到 8 个字，英文 2 到 3 个单词。
• 一致性：如果用了中划线命名，全图都用中划线；如果用了驼峰，全图都用驼峰。不要混用。

另外，我习惯在节点名字下方用小字标注技术栈或版本，比如order-service下面写Spring Boot 3.x。这样评审时不用额外解释，信息密度也上去了。

3.4 注释与图例：别让读者猜

图例是 diagram-design 里最容易被省略但最不该省略的部分。一张没有图例的图，读者只能靠猜。我的做法是：任何非标准视觉元素都必须有图例。比如你用了红色虚线表示“降级方案”，那图例里就要写清楚。

注释的使用也有技巧。我通常把注释放在图的右侧或下方，用编号跟图中的节点对应。比如图中节点旁边标个 ①，右侧写“① 该服务在高峰期 QPS 超过 5000 时会触发限流”。这样既不破坏图的整洁，又能补充关键信息。

注意：图例和注释不要超过图本身面积的 30%。如果注释太多，说明这张图承载了太多信息，应该拆图。

3.5 版本与变更：图是会过期的

这是最痛的一点。我见过太多文档里的图还是两年前的版本，服务早就拆了，图里还画在一起。diagram-design 要求每张图都有版本号和最后更新日期，并且跟代码一样进版本管理。

我的做法是在图下方加一行小字：v2.3 | 最后更新：2024-06 | 变更：新增库存服务异步通知。这样读者一眼就知道这张图的新旧程度。如果图是用代码生成的，直接跟代码仓库关联，每次合并请求自动更新图，根本不会过期。

4. 实操过程：从零开始设计一张架构图

4.1 第一步：明确读者和目的

动手之前先问自己三个问题：

1. 这张图给谁看？开发、产品、运维还是老板？
2. 他们看完后要做什么决策？评审通过、排期开发还是汇报？
3. 他们最关心什么？性能、成本、还是交付时间？

这三个问题的答案决定了图的粒度和重点。比如给老板看的图，重点画业务价值和系统边界，技术细节全部收起来；给开发看的图，重点画接口和依赖，业务背景一笔带过。

4.2 第二步：列出所有元素并分层

拿一张纸，把所有想画的服务、中间件、数据库、外部系统列出来。然后按前面说的三层法分类：

• 核心层：必须出现在主图上的，通常不超过 7 个。
• 支撑层：为了理解核心层而存在的，可以放在主图边缘或者用浅色表示。
• 细节层：放到注释或第二张图。

我通常会做一个表格来管理这些元素：

4.3 第三步：选择布局并画草图

根据元素之间的关系选择布局。如果是调用链，从左到右；如果是分层，从上到下。先用纸笔或者白板画草图，不要打开工具。这个阶段目标是快速试错，画错了擦掉重来，成本极低。

我画草图时会用不同颜色的笔：黑色画主流程，蓝色画数据存储，红色画风险点。这样即使草图很粗糙，评审时也能快速指出问题。

4.4 第四步：用代码生成正式图

草图确认后，用代码生成工具出正式图。以 PlantUML 为例，下面是一个简化版的订单系统架构图代码：

@startuml skinparam componentStyle rectangle actor "用户" as user component "API 网关" as gateway component "订单服务" as order component "库存服务" as inventory queue "消息队列" as mq database "订单库" as orderDb database "库存库" as inventoryDb user --> gateway : HTTPS gateway --> order : 创建订单 order --> orderDb : 写入 order --> mq : 发送库存扣减消息 mq --> inventory : 异步消费 inventory --> inventoryDb : 扣减库存 note right of mq 削峰填谷 失败进入死信队列 end note @enduml

这段代码生成的图，结构清晰，箭头方向统一，注释也到位。更重要的是，它可以进 Git，每次修改都有记录。

4.5 第五步：评审与迭代

图不是画完就完了。评审时我会重点观察三件事：

• 有没有人问“这个箭头是什么意思”——说明视觉编码不清晰。
• 有没有人问“这个服务为什么在这里”——说明分层有问题。
• 有没有人问“如果这里挂了怎么办”——说明风险点没标出来。

每次评审后更新图，并在图下方记录变更。通常迭代两到三轮，图就稳定了。

5. 常见问题与排查技巧实录

5.1 图太复杂，读者看不懂怎么办

这是最高频的问题。我的排查顺序是：

1. 先看节点数量：超过 15 个节点，几乎肯定需要拆图。
2. 再看箭头数量：箭头交叉超过 5 处，说明布局有问题，尝试调整节点位置或换布局方向。
3. 最后看颜色数量：超过 5 种颜色，读者会眼花。我的经验是主色不超过 3 种，辅助色不超过 2 种。

如果拆图后还是复杂，说明你对信息的理解还不够透彻。这时候应该回到第一步，重新做信息分层。

5.2 不同角色对图的理解不一致

这个问题通常是因为图里混用了不同抽象层次的概念。比如把“业务模块”和“部署单元”画在同一层。解决办法是按角色出图：给产品的图只画业务模块，给开发的图只画服务和技术栈，给运维的图只画部署单元。

如果必须在一张图里表达多个层次，用分组框隔开。比如上半部分画业务架构，下半部分画技术架构，中间用一条虚线分开。

5.3 图更新不及时，文档过期

这个问题的根源是图没有跟代码或文档一起管理。我的解决方案是：

• 用代码生成图，跟代码仓库放在一起。
• 在合并请求里强制检查图是否需要更新。
• 图下方标注版本和日期，过期图直接标记“已废弃”。

我们团队曾经有一张图过期了半年没人发现，后来在评审时被新同学指出，非常尴尬。从那以后，所有图都必须跟代码一起更新，否则合并请求不通过。

5.4 工具太多，不知道选哪个

下面这张表是我对不同场景的工具推荐：

提示：不要同时用太多工具。我见过一个团队同时用三种工具画图，结果风格不统一，维护成本极高。选一个主力工具，其他场景用最轻量的方式补充。

5.5 评审时没人看你的图

如果评审时大家都在低头看手机，说明你的图没有抓住他们的注意力。我的经验是：图要放在文档最前面，并且配一句话结论。比如“本方案通过消息队列解耦订单和库存，预计降低高峰期超时率 80%”。这句话就是钩子，读者会带着问题去看图。

另外，评审时不要从头讲到尾，先讲结论，再讲图。如果结论大家认可，图只是佐证；如果结论有争议，图就是讨论的基础。

6. 我踩过的坑和最后分享的几个技巧

第一个坑是过度追求美观。早期我花大量时间调颜色、对齐、加阴影，结果评审时被一句“这个服务为什么依赖那个”问住。后来我明白了，图的美观度只要达到“不干扰理解”就行，逻辑才是核心。

第二个坑是图里塞了太多技术细节。比如把数据库字段、接口参数都画进去，结果图变成了代码的图形化版本，没人看。技术细节应该放在文档正文，图只负责表达结构和关系。

第三个坑是不写图例。我曾经画了一张图，用了不同颜色的虚线表示不同含义，但没写图例。评审时有人问“这条红色虚线是什么意思”，我才发现只有我自己知道。从那以后，任何非标准元素都必须有图例。

最后分享几个实用技巧：

• 用灰度测试：把图转成黑白，如果还能看懂，说明视觉编码不依赖颜色，更可靠。
• 用“三秒测试”：给同事看三秒，然后问他这张图讲了什么。如果他说不出来，说明图需要简化。
• 用“反向画图”：从结果倒推，先画最终状态，再补中间过程。这样不容易漏掉关键节点。
• 用“图配文”：每张图下面配一段 100 字以内的说明，讲清楚这张图回答什么问题。读者可以先看图，再看文，效率更高。

这套 diagram-design 的方法，我在多个项目里反复用过，从单体架构到微服务拆分，从内部评审到对外汇报，基本都能覆盖。它不是银弹，但能让你少走很多弯路。如果你现在手里正好有一张画了很久但没人看懂的图，不妨按上面的步骤重新拆一遍，大概率会有惊喜。