1. 从“diagram-design”这个标题说起：它到底在解决什么问题
第一次看到“diagram-design”这个标题，很多人会以为它只是一个画图工具的教程，或者某个设计软件的介绍。但如果你真正做过系统设计、写过技术方案、画过架构图，就会明白这四个字背后藏着一个非常具体且高频的痛点：图不是画不出来，而是画出来之后没人看得懂、没人愿意看、过两周连自己都看不懂。
我做过一个粗略的统计，在技术方案评审会上，超过一半的沟通成本消耗在“这张图到底想表达什么”上。箭头指向混乱、模块层级不清、颜色使用随意、图例缺失、跨团队术语不统一——这些问题几乎出现在每一份初稿里。而“diagram-design”这个主题，本质上要解决的不是“用什么工具画图”，而是“如何让图成为一种高效、准确、可维护的沟通媒介”。
这个内容适合谁？如果你是后端开发、系统架构师、技术文档写作者、产品经理，或者任何需要把复杂逻辑用图表达出来的人，这篇内容都值得花时间看完。它不依赖某个特定软件，而是聚焦于设计思维和落地方法。你可以用Visio、draw.io、Excalidraw、Figma，甚至手绘，核心逻辑是通用的。
接下来我会从“为什么大多数图是失败的”开始，逐步拆解一套可复用的图表设计方法，包括信息分层、视觉编码、布局策略、评审检查清单，以及我在实际项目中踩过的坑和总结出的经验。全文没有空洞的理论，每一部分都对应着可以直接抄作业的操作步骤。
2. 为什么你画的图总是被吐槽：三个根因与对应解法
2.1 根因一：把“画图”当成了“记录”，而不是“翻译”
很多人画图时的心理活动是这样的：“我要把系统里所有的模块都放上去，把所有调用关系都画出来，这样才完整。”于是图上出现了三十多个方框、上百条连线，密密麻麻像电路板。这种图的本质是把代码结构或部署清单直接翻译成了图形，而不是对信息进行二次加工。
正确的做法是：画图之前先问自己——这张图是给谁看的？他需要从中获取什么信息？如果是给上级做决策，图应该突出关键路径和风险点；如果是给新同事做培训，图应该强调模块职责和数据流向；如果是给自己做备忘，图可以更随意但必须标注时间点和版本。
我习惯在画图前写一句话：“这张图要回答的问题是______。”如果这句话写不出来，说明还没想清楚，不要急着打开工具。
2.2 根因二：视觉编码没有统一规则，读者需要“猜”
视觉编码指的是用颜色、形状、线条样式、大小来承载信息。很多图的问题在于：红色有时表示“危险”，有时表示“核心模块”，有时只是随手选的；虚线有时表示“异步调用”，有时表示“待实现”，有时只是画错了懒得改。
一个可落地的规则是：在图的角落放一个图例，并且严格限制编码维度。比如：
| 视觉元素 | 含义 | 使用限制 |
|---|---|---|
| 实线箭头 | 同步调用 | 必须标注接口名或动作 |
| 虚线箭头 | 异步消息 | 必须标注消息主题 |
| 蓝色填充 | 本系统负责 | 不超过总模块数的60% |
| 灰色填充 | 外部依赖 | 必须标注依赖方名称 |
| 红色边框 | 本次变更涉及 | 仅用于变更评审图 |
这个表格看起来简单，但我在实际项目中推行时发现，光是“严格限制编码维度”这一条，就能让图的清晰度提升一个档次。因为人的短期记忆只能同时处理4到7个信息块，视觉编码超过这个数量，读者就会开始混淆。
2.3 根因三：布局随意，阅读路径不明确
人看图是有习惯路径的。对于大多数技术图，读者默认从左到右、从上到下阅读。如果你的图把入口放在右下角，出口放在左上角，读者会本能地感到困惑，即使逻辑本身是对的。
布局的核心原则是：让信息流和阅读流一致。具体操作上，我推荐三种经过验证的布局模式：
- 水平分层：适合展示请求处理流程，从左到右依次是接入层、逻辑层、存储层。每层内部从上到下排列模块。
- 垂直分层：适合展示架构层次，从上到下依次是用户层、应用层、服务层、数据层。每层内部从左到右排列模块。
- 中心辐射：适合展示以某个核心组件为中心的依赖关系，核心放中间，相关模块围绕四周，用距离表示耦合度。
选择哪种布局，取决于你想让读者最先看到什么。如果最重要的是“数据从哪来到哪去”，用水平分层；如果最重要的是“系统分几层”，用垂直分层；如果最重要的是“核心组件是谁”，用中心辐射。
3. 动手之前先定规则：图表设计的四个前置决策
3.1 决策一：确定图的“粒度”和“边界”
粒度指的是图中每个方框代表多大的东西。是一个微服务？一个模块？一个类？还是一个函数？边界指的是图的范围——是画整个系统，还是只画某个子系统？
这两个问题不先确定，画到一半一定会乱。我的经验是：一张图只表达一个粒度的信息。如果你想同时展示“系统间调用关系”和“类之间的继承关系”，请画两张图，不要挤在一张里。
具体操作上，我会在画图前写一个“范围声明”：
本图展示订单子系统与支付子系统之间的交互，粒度到服务级别，不涉及服务内部的模块划分。外部依赖仅标注名称，不展开细节。
这句话写在图的标题下方或备注里，读者一看就知道该期待什么、不该期待什么。
3.2 决策二：选择“静态结构”还是“动态行为”
静态结构图展示的是“谁和谁有关系”，比如架构图、部署图、组件图。动态行为图展示的是“事情怎么发生”，比如时序图、流程图、状态图。
很多失败的图是因为把两者混在一起：既画了模块的静态依赖，又画了某个请求的动态路径，结果读者分不清哪些线是永远存在的，哪些线是运行时才出现的。
我的建议是：静态图用实线表示永久关系，动态图用编号表示步骤顺序。如果确实需要在一张图里同时表达，用两种颜色区分，并在图例中明确说明。
3.3 决策三：确定“抽象层级”和“术语表”
抽象层级指的是图上的名词有多抽象。比如“用户服务”是一个抽象层级，“UserService类”是另一个层级，“getUserById方法”又是另一个层级。同一张图里混用不同层级，读者会感到跳跃。
术语表则是为了解决跨团队沟通问题。同一个东西，A团队叫“订单中心”，B团队叫“交易服务”，C团队叫“OMS”。图上如果混用，读者会以为是三个不同的东西。
我的做法是：在图的旁边附一个极简术语表，只列出图中出现的关键名词和它们的定义。比如：
| 图中名称 | 实际指代 | 负责团队 |
|---|---|---|
| 订单服务 | 订单创建、查询、状态管理 | 交易组 |
| 支付网关 | 对接外部支付渠道 | 支付组 |
| 消息队列 | 异步解耦和削峰 | 基础架构组 |
这个表不需要很详细，但能消除80%的歧义。
3.4 决策四：确定“更新频率”和“维护责任人”
一张图如果画完就没人管，三个月后就会变成“历史文物”。我在项目中见过太多这样的图：图上还画着已经下线的服务，新来的同事照着图去排查问题，结果越查越糊涂。
所以画图之前就要确定：这张图是一次性快照还是长期维护的活文档？如果是一次性的，标注日期和“仅反映当时状态”；如果是长期维护的，指定责任人，并约定更新触发条件（比如“每次架构变更后一周内更新”）。
这个决策看起来是管理问题，但它直接影响图的设计方式。一次性快照可以更随意，长期文档则需要更严格的规范和版本记录。
4. 从零到一：一张合格架构图的完整绘制流程
4.1 第一步：用纸笔列出所有“名词”和“动词”
不要一上来就打开绘图工具。先拿一张纸，左边写名词（系统、模块、服务、数据库、外部依赖），右边写动词（调用、发送、读取、写入、订阅）。这一步的目的是把脑子里的信息先倒出来，避免在工具里一边画一边想。
我通常会列到20到30个名词、10到15个动词，然后开始合并同类项。比如“用户信息查询服务”和“用户信息更新服务”可以合并为“用户服务”；“发送短信”和“发送邮件”可以合并为“通知渠道”。
合并的原则是：如果两个东西总是一起变化，就合并；如果它们独立变化，就分开。这个原则来自软件设计中的“单一职责”，在画图时同样适用。
4.2 第二步：确定主干路径，先画“一条线”
从入口到出口，先画出最主要的一条路径。比如“用户请求 -> 网关 -> 订单服务 -> 数据库 -> 返回”。这条线画出来之后，再往两边扩展分支。
这样做的好处是：保证图有一个清晰的“主动脉”，读者一眼就能抓住核心流程。很多图之所以乱，就是因为没有主干，所有模块平铺在一起，读者不知道从哪里开始看。
主干路径上的模块，我习惯用更粗的边框或更深的颜色，让它们在视觉上突出。分支路径则用细线或浅色，形成层次感。
4.3 第三步：添加边界和分组，用“容器”表达归属
边界和分组是降低认知负荷的利器。比如把所有属于“本系统”的模块放在一个浅色背景框里，把所有“外部依赖”放在另一个框里。这样读者不需要逐个阅读模块名称，就能快速区分内外。
分组的维度可以有很多种：按团队分组、按部署环境分组、按数据所有权分组、按变更频率分组。选择哪个维度，取决于你想回答什么问题。如果是给运维看的图，按部署环境分组最有用；如果是给安全评审看的图，按数据所有权分组最有用。
注意：分组框不要超过三层嵌套。超过三层，读者会迷失在框里。如果确实需要更多层次，拆成多张图。
4.4 第四步：标注关键信息，但不要过度标注
图上需要标注的信息包括：接口协议（HTTP、gRPC、消息）、数据格式（JSON、Protobuf）、关键参数（超时时间、重试次数）、重要约束（幂等、顺序性）。
但标注不是越多越好。我见过一张图，每条线上都写了五六个参数，结果图比代码还难读。我的原则是：只标注“如果不知道就会理解错”的信息。比如“异步”必须标，因为读者默认可能是同步；“最终一致”必须标，因为读者默认可能是强一致；“跨机房”必须标，因为读者默认可能是同机房。
其他细节可以放在图的备注里，或者单独写一份说明文档。
4.5 第五步：找一个人“试读”，验证信息传递效果
图画完之后，不要直接发出去。找一个没有参与设计的同事，给他五分钟看这张图，然后让他复述“这个系统是怎么工作的”。如果他复述的内容和你的设计意图一致，说明图是合格的；如果他在某个地方卡住了，那个地方就是需要修改的。
这个步骤我称之为“试读测试”，成本很低但效果极好。我自己的经验是，试读测试能发现至少30%的歧义问题，这些问题在作者眼里往往是不存在的，因为作者脑子里有完整的上下文。
5. 视觉编码的细节：颜色、形状、线条、文字的使用规范
5.1 颜色：不超过五种，且必须有语义
颜色是最容易被滥用的视觉元素。很多人画图时凭感觉选色，结果图上出现了十几种颜色，读者完全不知道每种颜色代表什么。
我的规范是：一张图的颜色不超过五种，每种颜色必须有明确的语义。比如：
- 蓝色：本系统核心模块
- 绿色：本系统辅助模块
- 灰色：外部依赖
- 橙色：本次变更涉及
- 红色：风险点或待解决问题
如果图上的模块超过五种分类，说明图的粒度太细了，应该拆图。另外，颜色不要作为唯一的信息载体，因为色盲读者可能无法区分。最好同时用形状或文字标注来辅助。
5.2 形状：方框、圆角框、圆柱、菱形各有含义
形状本身可以承载信息。常见的约定是：
- 直角方框：普通模块或服务
- 圆角方框：外部系统或第三方服务
- 圆柱：数据库或存储
- 菱形：判断或条件分支
- 平行四边形：输入或输出
这些约定不是强制的，但一旦你在一张图里用了，就要保持一致。我见过一张图里，数据库有时用圆柱、有时用方框、有时用云朵，读者会以为是三种不同的东西。
5.3 线条：实线、虚线、粗细、箭头方向
线条的规范比颜色更重要，因为线条直接表达关系。我的建议是：
- 实线箭头：同步调用或强依赖
- 虚线箭头：异步消息或弱依赖
- 无箭头实线：关联关系，无方向性
- 粗线：主要路径或高频调用
- 细线：次要路径或低频调用
箭头方向必须明确。如果两个模块互相调用，画两条箭头，不要画一条双向箭头，因为双向箭头无法表达“谁先谁后”或“谁主谁次”。
5.4 文字：字号、位置、对齐、缩写
文字是图上信息密度最高的元素，也是最容易出问题的。常见问题包括：字号太小看不清、文字压在线上、对齐混乱、缩写没有解释。
我的规范是：
- 模块名称字号不小于图内最小字号的1.2倍
- 文字放在模块内部居中，不要放在边框上
- 同一层级的模块名称左对齐或居中对齐，保持一致
- 缩写首次出现时必须给出全称，可以在图例或备注中说明
如果模块名称太长，用缩写，但缩写要在图例中解释。比如“用户身份认证服务”可以缩写为“认证服务”，然后在图例中写“认证服务 = 用户身份认证服务”。
6. 评审与迭代：如何让图在团队中真正被用起来
6.1 评审清单：十个问题快速判断图的质量
在把图发给别人之前，我会用下面这个清单快速过一遍：
- 这张图要回答的问题是什么？写出来了吗？
- 读者是谁？图的信息密度适合他吗？
- 有没有图例？图例中的编码规则是否被严格遵守？
- 主干路径是否清晰？读者能否在10秒内找到入口和出口？
- 颜色是否超过五种？每种颜色是否有明确语义？
- 线条样式是否一致？箭头方向是否明确？
- 术语是否统一？有没有混用不同团队的叫法？
- 关键约束是否标注？比如异步、最终一致、跨机房。
- 有没有过期信息？图上是否标注了日期和版本？
- 找一个没参与的人试读，他能否复述核心流程？
这个清单看起来简单，但能过滤掉90%的低质量图。我自己的经验是，每次评审前花五分钟过一遍，能节省评审会上半小时的扯皮时间。
6.2 迭代机制：图不是画完就结束，而是持续演进的
一张图的生命周期包括：创建、评审、发布、使用、反馈、更新、归档。很多团队只做了“创建”和“发布”，后面的环节全部缺失，导致图很快失效。
我的做法是：给每张图指定一个“图主”，负责收集反馈和触发更新。图主不一定是画图的人，但一定是最常使用这张图的人。更新触发条件包括：架构变更、接口变更、团队调整、每季度定期检查。
更新时不要直接改原图，而是创建一个新版本，保留旧版本。这样做的原因是：有些读者可能还在参考旧版本，突然变化会让他们困惑。版本号可以很简单，比如“v1.0”、“v1.1”，并在图的角落标注更新日期和变更摘要。
6.3 常见反模式：我踩过的五个坑
坑一：把图当成文档。我曾经试图在一张图里塞进所有信息，结果图变成了“图形化的文档”，没人愿意看。后来我明白，图的作用是“索引”和“导航”，详细内容应该放在文字文档里，图只负责建立整体认知。
坑二：追求工具的高级功能。有一段时间我沉迷于某绘图工具的高级特性，画了很多带阴影、渐变、3D效果的图。结果评审时，大家的注意力全在视觉效果上，没人讨论架构问题。后来我回归极简风格，只用最基本的方框和线条，沟通效率反而更高。
坑三：忽略读者的背景。我给管理层画的图，用了很多技术术语和细节，结果他们看不懂；我给开发画的图，过于抽象，结果他们觉得没有指导意义。后来我学会了“分层画图”：给管理层看一张高度抽象的概览图，给开发看一张详细的实现图，两张图用相同的术语和颜色规范。
坑四：不标注时间。一张没有日期的图，三个月后就是“薛定谔的图”——你不知道它是否还准确。现在我强制自己在每张图上标注创建日期和最后更新日期，过期图直接归档。
坑五：一个人闷头画。我曾经花了两天画了一张自认为很完美的图，结果评审时被指出一个根本性的理解错误。后来我养成了习惯：画到一半就找相关同事确认关键假设，避免在错误的方向上越走越远。
7. 工具选型：不同场景下的最优解
7.1 快速草图：纸笔或白板
如果是头脑风暴或早期讨论，纸笔和白板是最快的。不要一开始就打开软件，因为软件的操作成本会打断你的思路。我习惯用白板画草图，拍照片发到群里，大家先对齐大方向，再进入正式绘图。
白板草图的另一个好处是：它天然带有“未完成”的暗示，鼓励别人提出修改意见。而一张精美的电子图往往会让人产生“已经定稿”的错觉，不敢轻易挑战。
7.2 技术架构图：draw.io 或 Excalidraw
draw.io（现在叫diagrams.net）是我用得最多的工具，原因是：免费、跨平台、支持图层、支持自定义形状库、导出格式丰富。它的缺点是界面略显老旧，但对于技术架构图来说，功能完全够用。
Excalidraw 的优势是手绘风格，适合需要“不那么正式”的场合，比如内部讨论或创意评审。它的协作功能也很好，多人可以同时编辑。
7.3 产品设计图：Figma 或 FigJam
如果图需要和UI设计稿放在一起，Figma 是更好的选择。它的组件系统和自动布局功能，可以让图随着设计稿的变化而自动调整。FigJam 则适合团队协作和白板讨论。
7.4 复杂系统图：专业建模工具
如果系统非常复杂，需要严格的元模型和一致性检查，可以考虑专业的建模工具。这类工具支持UML、ArchiMate等标准，可以自动检查模型的一致性。但学习曲线较陡，适合大型团队或长期维护的项目。
提示：工具不是关键，规范才是。我见过用PPT画出高质量架构图的人，也见过用专业工具画出垃圾的人。先定规范，再选工具。
8. 把图用起来：从“画完就忘”到“团队资产”
8.1 图的存放位置和命名规范
图应该放在团队所有人都能访问的地方，比如内部Wiki、共享文档库或代码仓库。命名规范建议包含：系统名称、图类型、版本号、日期。比如：
订单系统-架构图-v1.2-20250115
这样命名的好处是：按名称排序时，同一系统的图会聚在一起，方便查找和对比。
8.2 图的引用和嵌入
图不应该孤立存在，而应该被引用在相关的文档、代码注释、工单系统中。比如在接口文档中嵌入架构图，在代码仓库的README中放部署图，在故障排查手册中放时序图。
引用的方式是：不要直接复制图片，而是放链接。这样图更新后，所有引用处自动看到最新版本。如果必须嵌入图片，标注版本号和日期，并定期检查是否过期。
8.3 图的培训和传承
新同事入职时，架构图是最好的培训材料之一。但前提是图必须准确、清晰、有注释。我习惯在新同事入职第一周，安排一次“看图讲解”，带着他过一遍核心架构图，解释每个模块的职责和关键设计决策。
这个过程中，新同事往往会提出一些“愚蠢”的问题，这些问题恰恰暴露了图中隐含的假设和未标注的约束。把这些问题的答案补充到图的备注中，图的质量会越来越高。
8.4 图的度量和反馈
如果想知道图是否真的有用，可以观察几个指标：图的访问量、引用次数、评审会上被引用的频率、新同事上手时间的变化。这些指标不需要很精确，但能帮你判断哪些图值得继续维护，哪些图可以归档。
我自己的经验是：一张图如果三个月内没有被任何人引用或讨论，大概率已经失效了。要么更新它，要么删掉它，不要让它继续误导别人。
9. 一些零散但实用的经验
画图这件事，说到底是“信息设计”的一个分支。它不需要很高的美术功底，但需要清晰的逻辑和对他人的同理心。我最后分享几个零散但很实用的经验，都是踩坑之后总结出来的。
第一，先写标题再画图。标题就是这张图的“一句话摘要”，如果标题写不清楚，图一定画不清楚。我习惯把标题写在最上方，字号比模块名称大一号，让读者第一眼就知道这张图在讲什么。
第二，用“读者视角”检查每一根线。每画一根线，问自己：读者看到这根线，会认为它代表什么？如果可能产生歧义，加标注或改样式。这个习惯能消除大部分误解。
第三，不要害怕留白。图上的空白不是浪费，而是呼吸空间。模块之间留出足够的间距，读者才能快速区分不同的组。我见过太多图，模块挤在一起，像早高峰的地铁，读者根本找不到重点。
第四，定期归档过期图。过期的图比没有图更危险，因为它会误导人。我每季度会花半小时清理一次图库，把过期的图移到“归档”目录，并在原位置留一个链接指向新图。
第五，把图画给未来的自己看。你现在觉得理所当然的上下文，三个月后可能完全忘记。所以图上要标注足够的背景信息，让未来的你能够快速恢复记忆。这个习惯让我在排查历史问题时节省了大量时间。
第六，图的最高境界是“自解释”。一张好的图，不需要作者在旁边讲解，读者自己就能看懂。如果你发现每次展示图时都要额外解释很多内容，说明图本身需要修改，而不是你的讲解不够好。
这些经验没有一条是“技术性”的，但它们比任何工具技巧都重要。因为画图的核心不是操作软件，而是组织信息、传递思想。工具会变，规范会变，但“让读者快速准确理解”这个目标永远不会变。
