diagram-design：用设计方法论重构技术图的信息架构与视觉规范

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

第一次看到 "diagram-design" 这个标题，很多人会以为它只是教你怎么画图——选个模板、拖几个框、连几条线，导出 PNG 就完事了。但真正做过技术方案、写过设计文档、给团队讲过架构的人都知道，画图这件事的痛点从来不在"画"本身，而在于图背后的信息结构是否清晰、是否可维护、是否能被不同角色快速理解。diagram-design 这个项目，本质上是在解决"如何用一套可复用的设计方法，把复杂系统、流程、关系用图讲明白"的问题。

我做了十多年技术方案和产品设计，画过的架构图、流程图、时序图、状态机图没有一千也有八百张。早期我也是那种"打开工具就开画"的人，结果就是：图越画越多，风格越来越乱，改一个模块要动五张图，同事看我的图还得先问我"这个框代表什么"。后来我才意识到，画图不是美术问题，是信息架构问题。diagram-design 这个项目标题吸引我的地方，就在于它把"diagram"和"design"放在一起——不是"diagram drawing"，而是"diagram design"，这说明它关注的是设计层面的方法论，而不是工具操作层面的技巧。

这篇文章适合几类人看：一是经常需要画架构图、流程图、关系图的技术同学；二是需要给非技术角色讲清楚复杂逻辑的产品或运营同学；三是带团队、需要统一团队图表达规范的管理者。不管你现在用的是哪款画图工具，这套设计思路都能直接迁移过去。我会从整体设计思路、核心细节、实操过程、常见问题四个维度，把 diagram-design 这件事拆透，让你看完就能上手改自己手里的图。

2. 整体设计思路拆解：为什么"先定规则再画图"比"先画再调"快十倍

2.1 图的本质是信息压缩，不是视觉装饰

很多人画图有个误区，觉得图越漂亮越好，于是花大量时间调颜色、加阴影、找图标。但 diagram-design 的核心思路恰恰相反：图的第一目标是降低理解成本，第二目标才是美观。一张好的架构图，应该让读者在 10 秒内抓住主干，30 秒内理解模块关系，2 分钟内能顺着图讲出整个流程。如果做不到这三点，再好看也是失败的。

我举个实际例子。之前有个团队给我看他们的系统架构图，密密麻麻 40 多个框，颜色有七八种，箭头交叉得像蜘蛛网。我问他们"核心链路是哪条"，三个人给了三个答案。这就是典型的"画了但没设计"。后来我们用 diagram-design 的思路重构：先确定这张图要回答什么问题（核心链路），再确定分层（接入层、逻辑层、存储层），最后才确定每个框的粒度。重构后框的数量没变，但理解成本降了一个数量级。

所以 diagram-design 的第一个设计原则是：先定义图的"问题域"，再定义图的"表达域"。问题域就是你画这张图要回答什么问题，表达域就是用什么图形元素来回答。顺序不能反。

2.2 分层设计：让每张图只讲一件事

diagram-design 里我特别认同的一个思路是"分层表达"。什么意思？就是不要试图用一张图讲完整个系统。系统越复杂，越要拆成多张图，每张图只负责一个视角。

常见的分层方式有这么几种：

• 按抽象层级分：业务架构图 → 应用架构图 → 技术架构图 → 部署架构图。越往下越具体，越往上越抽象。
• 按关注点分：静态结构图（有哪些模块）、动态流程图（模块怎么交互）、时序图（一次请求怎么走）、状态图（对象状态怎么变）。
• 按读者分：给老板看的图（讲价值和链路）、给开发看的图（讲接口和数据）、给运维看的图（讲部署和依赖）。

我自己的习惯是，任何一个稍复杂的系统，至少准备三张图：一张给非技术角色看的"业务全景图"，一张给开发看的"模块关系图"，一张给运维看的"部署拓扑图"。这三张图共用一套视觉规范，但粒度和视角完全不同。这样做的好处是，每张图都很干净，不会出现"一张图塞了所有信息，结果谁都看不懂"的情况。

2.3 视觉规范先行：颜色、形状、连线都要有语义

diagram-design 里最容易被忽视但最重要的部分，是视觉元素的语义化。什么意思？就是颜色不是随便选的，形状不是随便用的，连线不是随便连的，每一个视觉元素都对应一个明确的含义。

我见过太多团队的图，颜色纯粹是为了"好看"或者"区分"，结果同一个蓝色在这张图里代表"前端"，在另一张图里代表"数据库"，读者每次都要重新猜。这就是没有视觉规范。

一套好的 diagram-design 视觉规范，应该包含这几个维度：

这套规则一旦定下来，团队里所有人画图都遵循，读者看任何一张图都能快速解码。这就是 diagram-design 里"design"的真正含义——设计一套可复用的视觉语言，而不是设计一张好看的图。

2.4 工具选型：别让工具限制你的设计思路

说到工具，我的观点很明确：工具是次要的，规范是主要的。但工具确实会影响你的设计效率。我这些年用过各种画图方式，大致分三类：

• 代码化绘图：用文本描述图，工具渲染成图。优点是版本可控、易维护、适合放进代码仓库。缺点是有学习成本，复杂布局不好调。
• 拖拽式绘图：所见即所得，上手快。优点是直观、灵活。缺点是版本管理差、风格容易乱、改起来费劲。
• 白板式绘图：适合头脑风暴和快速沟通。优点是快。缺点是不适合做正式文档。

diagram-design 的思路是：正式文档用代码化或规范化的拖拽工具，沟通讨论用白板，两者不要混。我自己的做法是，架构图和流程图用代码化方式维护，放进项目仓库，跟代码一起版本管理；讨论阶段的草图用白板，讨论完就丢，不进入正式文档。这样既保证了正式文档的规范性，又保证了讨论的灵活性。

3. 核心细节解析与实操要点：从需求到成图的完整拆解

3.1 第一步：明确图的"读者"和"问题"

画图之前，先问自己三个问题：

1. 这张图给谁看？是给技术负责人、开发、产品、还是客户？不同角色关注的点完全不同。
2. 这张图要回答什么问题？是"系统有哪些模块"、"一次请求怎么走"、还是"数据怎么流转"？
3. 读者看完这张图要做什么决策？是评估方案、排查问题、还是理解现状？

这三个问题决定了图的粒度、视角和详细程度。我踩过的坑是：给开发看的图做得太抽象，开发说"看不懂怎么实现"；给老板看的图做得太细，老板说"我只想知道能不能按时上线"。后来我养成了一个习惯：画图前先在纸上写一句话，说明这张图的目标。如果这句话写不出来，说明我还没想清楚，那就先别画。

3.2 第二步：确定图的骨架结构

骨架结构就是图的主干。常见的骨架有几种：

• 分层结构：适合架构图。从上到下依次是接入层、逻辑层、存储层，或者从前到后依次是前端、网关、服务、数据库。
• 流程结构：适合流程图。从左到右或从上到下，按时间或逻辑顺序排列节点。
• 中心辐射结构：适合关系图。中心是核心模块，周围是依赖模块。
• 泳道结构：适合跨角色流程图。每个角色一条泳道，节点放在对应泳道里。

选哪种骨架，取决于你要表达的核心关系。如果是"谁依赖谁"，用分层或中心辐射；如果是"先做什么后做什么"，用流程或泳道。我自己的经验是，架构图优先用分层，流程图优先用泳道，这两种结构最不容易乱。

3.3 第三步：定义视觉规范并严格执行

这一步是 diagram-design 的核心。我建议在动手画之前，先花 10 分钟定义好这套图的视觉规范。具体包括：

• 颜色表：列出所有会用到的颜色，每个颜色对应一个语义。比如蓝色系代表业务服务，绿色系代表数据，橙色系代表外部依赖，灰色系代表基础设施。
• 形状表：列出所有会用到的形状，每个形状对应一个语义。比如矩形代表服务，圆柱代表数据库，菱形代表判断，圆角矩形代表模块。
• 连线表：列出所有会用到的连线样式，每种样式对应一个语义。比如实线箭头代表同步调用，虚线箭头代表异步消息，带数字的线代表顺序。
• 字号规范：标题、模块名、注释分别用什么字号，保证层级清晰。

这套规范一旦定下来，就要严格执行。我见过太多图，规范定了但没人遵守，结果还是乱。我的做法是，把规范写进团队的文档模板里，新人入职第一件事就是学这套规范。另外，规范不要定得太复杂，颜色控制在 5 种以内，形状控制在 4 种以内，否则记不住也用不起来。

3.4 第四步：控制信息密度，该拆就拆

一张图的信息密度是有上限的。我的经验值是：一张图里的核心模块不超过 9 个，总元素不超过 20 个。超过这个数，读者就开始迷失了。

如果信息确实多，怎么办？拆图。拆图的方式有几种：

• 按层级拆：总览图 + 各层详细图。
• 按流程拆：主流程图 + 各子流程详细图。
• 按模块拆：系统总图 + 各模块内部图。

拆图的时候要注意，每张图都要能独立看懂，不能出现"这张图必须配合另一张图才能理解"的情况。我的做法是，每张图都带一个简短的图例和说明，说明这张图的视角和边界。

3.5 第五步：标注和注释要克制但精准

图上的文字标注，原则是能少则少，但关键信息不能少。我见过两种极端：一种是图上只有框和线，没有任何文字，读者完全靠猜；另一种是每个框里塞了一大段文字，图变成了文档。

我的做法是：

• 模块名用简短的名词，控制在 6 个字以内。
• 关键参数（如 QPS、延迟、容量）用数字标注在连线或模块旁边。
• 复杂逻辑用编号 + 图下注释的方式，不在图上写长句。
• 图例必须要有，说明颜色、形状、连线的含义。

提示：图例不是可有可无的装饰，它是读者解码这张图的钥匙。我见过很多图没有图例，读者只能靠猜，这是设计上的失职。

3.6 第六步：版本管理和迭代

图是要迭代的。系统变了，图也要跟着变。所以 diagram-design 里很重要的一点是图的版本管理。

如果用的是代码化绘图，天然就有版本管理，跟代码一起提交就行。如果用的是拖拽工具，建议把源文件也放进版本管理系统，每次修改都提交，并写清楚改了什么。我自己的习惯是，图的文件名带版本号和日期，比如architecture-v2.3-20240115，这样一眼就能看出是不是最新版。

另外，图要有"废弃标记"机制。老版本的图不要直接删，标记为"已废弃"并注明废弃日期和替代图，避免有人还在用老图做决策。

4. 实操过程与核心环节实现：手把手带你走一遍完整流程

4.1 场景设定：一个典型的系统架构图需求

假设你现在要为一个中等规模的系统画一张架构图，这个系统包含前端、网关、若干业务服务、消息队列、缓存、数据库，还有几个外部依赖。团队里有开发、产品、运维三类角色要看这张图。你需要在半天内完成这张图并让三方都认可。

这个场景很典型，我拿它来完整走一遍 diagram-design 的流程。

4.2 第一步：需求澄清（约 20 分钟）

先跟三类读者各聊 5 分钟，搞清楚他们各自关心什么：

• 开发关心：模块怎么划分、接口怎么调、依赖关系是什么。
• 产品关心：核心链路是什么、用户请求怎么走、有哪些外部依赖。
• 运维关心：部署单元有哪些、依赖哪些中间件、容量瓶颈在哪。

聊完之后你会发现，三类角色的关注点差异很大，一张图很难同时满足。所以结论是：至少画两张图。一张"业务链路图"给产品和开发看，一张"部署拓扑图"给运维看。如果时间紧，先画业务链路图，因为看的人最多。

4.3 第二步：确定骨架和粒度（约 15 分钟）

业务链路图用分层结构，从上到下依次是：

1. 接入层：前端、网关
2. 业务层：各业务服务
3. 中间件层：消息队列、缓存
4. 存储层：数据库
5. 外部依赖：放在右侧单独一列

粒度控制在：接入层 2 个框，业务层 4-5 个框，中间件层 2 个框，存储层 2 个框，外部依赖 2-3 个框。总共 12-14 个框，符合信息密度上限。

4.4 第三步：定义视觉规范（约 10 分钟）

针对这张图，定义如下规范：

这套规范定下来之后，画图的时候直接套用，不用每次纠结用什么颜色。

4.5 第四步：绘制主干（约 40 分钟）

先画核心链路：用户请求 → 前端 → 网关 → 核心业务服务 → 缓存/数据库。这条链路用加粗连线标出，让读者一眼就能看到主干。

然后画辅助链路：业务服务之间的调用、业务服务到消息队列的异步消息、业务服务到外部依赖的调用。这些用普通连线。

最后画存储层和中间件层的内部关系，比如缓存和数据库的读写关系。

画的时候注意几点：

• 连线尽量走直线或直角，不要斜着连，斜线多了图就乱。
• 连线交叉尽量少，如果实在避不开，用"跳线"符号表示不连接。
• 模块对齐要整齐，同一层的模块顶部或中心对齐。

4.6 第五步：标注和注释（约 20 分钟）

在关键连线上标注核心参数，比如网关到业务服务的 QPS、业务服务到数据库的延迟。参数不要标太多，只标读者关心的。

在图的下方加注释，说明：

• 图例：颜色、形状、连线的含义。
• 边界：这张图包含什么、不包含什么。
• 版本：图的版本号和日期。

4.7 第六步：评审和迭代（约 30 分钟）

把图发给三类读者各看一遍，收集反馈。常见的反馈有：

• "这个模块的粒度不对，应该拆成两个。"
• "这条链路不是核心链路，核心链路应该是另一条。"
• "这个外部依赖已经废弃了，不用画。"

根据反馈修改，然后再审一遍。一般两轮就能定稿。

4.8 第七步：归档和发布（约 10 分钟）

定稿后，把源文件和导出图一起归档，源文件放进版本管理系统，导出图放进文档系统。在文档系统里注明图的用途、读者、版本和更新日期。

注意：导出图的时候，建议同时导出 PNG 和 SVG 两种格式。PNG 用于快速查看，SVG 用于放大查看细节。另外，导出分辨率要足够高，避免放大后模糊。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 图太乱怎么办？先做减法再做加法

图乱是最常见的问题。我的排查思路是：

1. 先看框的数量：超过 20 个框，基本可以确定是信息密度过高，需要拆图。
2. 再看连线的数量：连线数量超过框数量的 1.5 倍，说明关系太复杂，需要抽象。
3. 再看颜色和形状：颜色超过 5 种、形状超过 4 种，说明视觉规范没定好。
4. 最后看对齐和间距：模块没对齐、间距不均匀，说明绘制时没注意排版。

排查完之后，先做减法：删掉不必要的信息，合并同类模块，抽象复杂关系。减到不能再减，再做加法：补充必要的标注和注释。

5.2 不同角色看不懂同一张图怎么办？拆图 + 图例

这是典型的"一张图想满足所有人"的问题。解决方案就是拆图，按角色拆，每张图配一个针对该角色的图例和说明。

如果实在只能画一张图，那就把图例做详细，在图例里说明"如果你是 XX 角色，重点看哪部分"。但我的经验是，拆图永远比一张图硬撑要好。

5.3 图改起来太费劲怎么办？用代码化绘图

拖拽式绘图最大的问题就是改起来费劲。改一个模块名，可能要调整周围所有模块的位置。代码化绘图就没这个问题，改文本就行，布局自动调整。

我推荐的做法是：正式文档用代码化绘图，讨论草图用白板。代码化绘图工具的选择上，优先选支持版本控制、支持自动布局、支持导出多种格式的。具体用哪款，看团队习惯，这里不展开。

5.4 图例没人看怎么办？把图例做进图里

图例没人看，是因为图例和图分离了。解决方案是把图例做进图里，比如用颜色直接标注在模块上，或者用形状直接表达语义，让读者不需要看图例就能理解。

当然，完全不需要图例是不现实的，但可以尽量减少对图例的依赖。我的做法是，颜色和形状的语义尽量符合直觉，比如绿色代表数据、蓝色代表服务、橙色代表外部，这样读者即使不看图例也能猜个八九不离十。

5.5 常见问题速查表

5.6 几个我踩过的坑

坑一：颜色选太多。早期我喜欢用各种颜色区分模块，结果图看起来像彩虹，读者反而更晕。后来我把颜色控制在 4 种以内，每种颜色对应一个明确的语义，图立刻清爽了。

坑二：连线交叉太多。连线交叉是图乱的主要原因之一。我的经验是，画连线之前先规划好模块位置，让连线尽量短、尽量直、尽量少交叉。如果实在避不开，用跳线符号。

坑三：图例写得太复杂。图例是给读者快速解码用的，不是给作者炫技用的。图例要简短、直观、符合直觉。我见过一个图例写了 20 行，读者看完图例已经忘了图长什么样。

坑四：不写边界说明。每张图都有边界，说明这张图包含什么、不包含什么。不写边界说明，读者容易误以为图里没有的就是不存在的。我现在的习惯是，每张图下面都写一句"本图仅包含 XX 范围，XX 不在本图范围内"。

坑五：不更新。图画完就不管了，系统变了图没变，结果图变成了误导。我的做法是，把图的更新纳入变更流程，系统变更时必须同步更新图，否则变更不算完成。

6. 进阶技巧：让 diagram-design 从"能用"到"好用"

6.1 建立团队级的图库和模板

一个人画得好不算好，团队都能画好才算好。我的做法是，建立团队级的图库和模板，把常用的架构模式、流程模式做成模板，新人直接套用。模板里包含视觉规范、图例、注释格式，新人只需要填内容，不需要从零设计。

图库则用来沉淀历史图，按项目、按系统、按时间分类，方便查找和复用。图库里的图要定期清理，废弃的图标记清楚，避免误用。

6.2 用"图 + 文"组合表达复杂逻辑

图擅长表达结构和关系，不擅长表达逻辑和条件。所以复杂逻辑要用"图 + 文"组合表达。图负责主干，文负责细节。

我的做法是，图下面配一段简短的说明，说明图里的关键逻辑、边界条件、异常情况。说明控制在 200 字以内，太长就单独写文档。

6.3 定期做图的"健康检查"

图跟代码一样，会腐化。所以要定期做健康检查，检查内容包括：

• 图是否还准确反映系统现状。
• 视觉规范是否还被遵守。
• 图例和注释是否还清晰。
• 是否有废弃的图还在被引用。

健康检查的频率，建议跟系统变更频率挂钩。变更频繁的系统，每季度检查一次；变更少的系统，每半年检查一次。

6.4 把图纳入代码评审流程

如果团队用代码化绘图，可以把图的变更纳入代码评审流程。每次改图都走评审，确保图的变更经过确认，避免随意改图导致的不一致。

这个做法一开始可能觉得麻烦，但坚持下来会发现，图的准确性和一致性会大幅提升。我自己的团队就是这么做的，效果很好。

6.5 培养"图感"：多看好的图，多画多改

最后说一点软性的东西：图感。图感这东西，跟代码感一样，是靠多看多画多改练出来的。我的建议是，平时多看好图，看到好的图就存下来，分析它为什么好。自己画图的时候，画完先放一放，过半天再看，往往能发现新的问题。

我个人的体会是，画图这件事，前期花在思考上的时间越多，后期花在修改上的时间越少。很多人画图慢，不是因为手慢，是因为想得少，画完才发现不对，然后反复改。先把问题想清楚，把结构定下来，把规范定好，画图其实很快。

这个内容后续还可以这样扩展：一是针对不同类型的图（架构图、流程图、时序图、状态图）分别写详细的设计规范；二是针对不同工具（代码化、拖拽式、白板式）分别写实操指南；三是针对不同角色（开发、产品、运维、管理层）分别写图的阅读指南。这些方向我后续会陆续展开，感兴趣的话可以持续关注。