在团队里待久了你会发现一个有意思的现象：需求评审、技术方案、项目复盘，几乎每一次重要沟通都离不开图。架构图、流程图、时序图、ER 图，谁都能画上两笔，但真正能画到“拿得出手”“讨论得起劲”“半年后还有人愿意翻出来看”的图，其实不多。diagram-design 要解决的就是这件事——把脑子里那些散着的模块、依赖关系、流转路径，整理成一张别人能看懂、能讨论、能继续修改的图。
这篇文章不会教你怎么点某个软件里的按钮，而是把图表设计当成一套完整的方法来讲。我会结合这些年画架构图、流程图、部署图、数据模型图踩过的坑，讲清楚画图前要想什么、画的时候怎么组织、画完之后怎么维护，最后还会给一份可以直接抄的排查思路。这套东西适合正在带项目、需要靠图讲清楚方案的同学，也适合刚入行、想让自己的图从“能看”变成“好用”的工程师、产品经理和设计师。
1. 为什么要把“画图”当成一个正经事来做
很多人的工作流里，图是“顺手画的”：开会前十分钟打开画板，拉几个框框，连几条线，完事直接投到屏幕上。这么干确实能应付一场会，但它很难应付一个项目。项目的生命周期少则几个月，多则几年，图一旦成为多方协作、评审、排期、交接的参照物，它就不再是草稿，而是一份需要被严肃对待的工程资产。
1.1 图表到底算什么：从临时草稿到团队共识
我先说一个自己的判断：一张好的技术图，本质上是“团队共识的可视化快照”。架构图背后是大家认可的模块划分，流程图背后是大家对业务规则的统一理解，时序图背后是对一次交互路径的完整对齐。图的真正价值不在于它画得多精美，而在于它是否能帮一群人把认知对齐到同一个基准线上。
这也解释了为什么很多图会越画越烂——因为画图的人把注意力放在了“好看”上，一会儿调颜色，一会儿拖对齐，却忽略了这张图要替团队回答的核心问题。你问一个画图的人“这张图想表达什么”，如果他支支吾吾答不上来，那这张图不管多漂亮，本质上都是不合格的。
我在实际项目中会把图分成三个层级：第一种是草稿，自己画给自己看，梳理思路用的，怎么乱都行；第二种是讨论稿，给两三个核心同事看，目标是快速暴露分歧；第三种是共识稿，通常是评审会、文档、对外协作里出现的图，它需要在较长一段时间内核、可维护。diagram-design 的大部分方法，针对的都是第二种和第三种图。
1.2 四类最常画的图，以及它们的“表达职责”
不同类型的图承担着不同的表达任务，很多人画不好图，是从第一步就选错了图型。我整理了一下自己在技术文档、项目汇报和故障复盘里最常用的四种类型：
- 架构图：表达系统的静态结构，回答“系统由哪些部分组成”“各部分之间什么关系”。常见形态有分层架构图、调用关系图、部署拓扑图。
- 流程图：表达动态过程，回答“一件事从开始到结束经历了哪些步骤”“分支和异常怎么处理”。常见形态有业务流程图、状态机图、泳道图。
- 时序图：表达跨对象的交互顺序，回答“一次完整请求里谁先调用谁、消息怎么往返”。调试接口、梳理日志链路时特别好用。
- 数据模型图：表达数据实体和关系，回答“有哪些实体、字段、主外键、一对多还是一对一”。建表、接口字段设计、数据迁移时基本绕不开。
这四类图没有高低之分，只有合适不合适。你非要在理解业务流程的时候用一张严谨的 ER 图去表达，结果就是大家盯着外键关系翻来覆去地看，真正的业务分支反而没人讨论。反过来，你想让数据库设计评审会变得高效，递一张业务泳道图上去，也一样会遭到 DBA 的连环追问。
1.3 画图前先问自己的三个问题
我现在每画一张图之前，会强制自己在标题或者备注里写清楚三件事：给谁看、解决什么问题、在哪里被使用。这三个问题看着简单，但能过滤掉至少一半的无效画图。
给谁看决定了信息的抽象层级。画给技术委员会看，你要展示的是模块边界、关键依赖、风险点；画给新入职的同学看，你要展示的是项目入口、核心流程和常见坑位。同一套系统，两种受众，画出来的图完全可以长得不一样。解决什么问题决定了图的中心，一张图只解决一个核心问题，不要指望一张图既能讲清楚系统全局，又能暴露每一个接口的超时重试细节。在哪里被使用决定了图的生命周期，如果是放在 wiki 里长期维护的架构图，你需要考虑后续怎么更新；如果是 PPT 里一页过场动画，那画得再糙问题也不大。
2. 好的图表设计，核心就这五个原则
说完了“道”的层面，接下来进入“术”的部分。我总结了一套自己画图时反复对照的检查清单，总共有五条：用途定类型、层级定边界、命名定共识、视觉定重点、维护定寿命。这五条不是学术总结，全是实际项目里被教训出来的。
2.1 先定用途，再选图表类型：一张速查表
很多画图新手会问“我要画架构图，用什么工具好”，我通常会反问一句“你画的是哪种架构图”。同样是架构图，分层架构图、依赖图、部署拓扑图的画法和工具选择完全不一样。这里给大家一张我常用的选型速查表：
| 你想回答的核心问题 | 合适的图型 | 常用落地场景 |
|---|---|---|
| 系统由哪些模块组成、如何分层 | 分层架构图 / 模块关系图 | 方案设计、系统概览 |
| 服务与依赖之间如何调用 | 调用链图 / 依赖图 | 故障排查、性能分析 |
| 请求在多个对象间如何流转 | 时序图 | 接口设计、链路梳理 |
| 业务流程有哪些分支和异常 | 流程图 / 泳道图 | 需求分析、流程优化 |
| 数据实体及关系如何组织 | ER 图 / 数据字典图 | 数据库设计、迁移方案 |
| 服务如何部署在机器/集群上 | 部署拓扑图 | DevOps、扩容演练 |
这张表不能解决所有问题，但它能让你在动笔之前停下来想一下：我到底要回答什么。图型选对了，后面再烂也烂不到哪去；图型选错了，越精美越尴尬。
2.2 层级与边界：一张图只讲一件事
很多人画图失控的起点，是想在一张图里放太多东西。我有一次画一个中台系统的架构图，什么网关、鉴权、消息队列、分布式事务、每一个微服务、每一条调用链路都想塞进去，结果画出来以后，A4 纸横过来连字号缩到 6 号都放不下。评审会上大家盯着密密麻麻的线条沉默了半天，最后只说出一句“太复杂了，看不出来重点在哪”。
从那以后我给自己定了一条规矩：一张图只讲一件事，讲不透就拆成两张、三张。想表达系统全貌，先画一张分层清晰的概览图；想深入讲某个核心模块，再画一张这个模块的详细依赖图。概览图和详细图之间通过“模块名称+版本”建立引用关系，读者想看细节的时候自然能找到对应文档。
这条原则用一句话概括就是：好的图敢于留白，敢于不做。把不重要的链路虚化、折叠，或者干脆不画，反而能让关键路径变得醒目。很多优秀的技术博客里的架构图都很“简洁”，不是因为他们系统简单，而是他们懂得做取舍。
2.3 命名与标注：把“盒子里写什么”当回事
如果说布局决定了一张图能不能看，那么命名决定了一张图能不能被准确讨论。我见过太多图，里面的框框写的是“服务A”“模块B”“对接系统”，这种命名在画图的当下谁都懂，但过两周再回来看，没人记得“服务A”到底是哪个服务。
我的习惯是，图中的每个关键节点，第一优先写业务/系统名称，第二优先写清楚它的职责，而不是笼统的编号。比如“订单服务（负责下单、支付回调、超时关单）”就比“订单服务”好得多；如果图层级比较高，还可以在括号里标注当前版本号，方便和代码仓库对上。与其花时间改线宽、调阴影，不如先把每个框框的名字想清楚。
另外，所有缩写、内部黑话、只有团队才知道的代号，第一次出现的时候必须加注释。不是所有人都懂“GLB”“CIF”“IDC”这些缩写，图是给人看的，不是给搜索引擎看的，降低阅读门槛比酷炫更重要。
2.4 视觉降噪：删掉那些没用的线
图里最有价值的信息是关系和节点，但大家看一张图第一眼看到的往往是线条和颜色。线条一多、交叉一多，整张图的信息熵就会暴涨。我自己的视觉降噪经验有这么几条：
- 一个节点最好只保留一个主要出口方向，控制在四个方向以内，避免星型连接。
- 超过两层嵌套的容器要慎重，三层以上读者基本就分不清内外了。
- 同一层级的节点使用相同的形状和颜色，层级间的跳变才靠箭头方向来表达。
- 虚线只用来表达异步、弱依赖、未来规划，不要随意混用，不然读者会开始纠结“这条虚线到底表示什么”。
线条是图的语法，语法混乱的时候读者会把大部分精力花在“破译”上，而不是理解内容。每次画完图之后，我都习惯性地站在三米外眯着眼看一眼：如果这个距离上还能一眼分清主链路和辅助节点，这张图基本合格了。
3. 实操全流程：从一张只有三个框的草图开始
方法论讲多了容易飘，这节我从一个真实的小项目出发，完整走一遍图表设计流程。这个项目的背景是：给一个内部订单系统梳理“下单后完整链路”，参与的人有后端、前端、测试和运维，最终成果要沉淀到团队 wiki 上。
3.1 工具选型：我平时用的那几款
先聊工具，因为这是大家问得最多的问题。我的原则是：用什么工具不重要，重要的是团队的协作习惯和图的维护成本。下面是我实际用过的组合：
- markdown 原生图（比如 Mermaid）：适合嵌入文档、PR 描述里，版本管理天然友好，改动走 git diff 就能看到，适合持续维护的“活文档”。
- draw.io / diagrams.net：免费、离线可用、文件是纯 XML，可以直接存进代码仓库，适合画比较灵活的架构图、部署图，也适合多人协作编辑。
- Excalidraw：手绘风格，适合低保真快速草稿、头脑风暴、快速对齐认知。画出来的图有一种“我还没定稿，大家随便提意见”的心理暗示，反而有利于讨论。
- PlantUML：DSL 驱动画 UML 类图、时序图，适合对格式统一要求高、又不想手工对齐的场景，缺点是调样式比较费劲。
- Figma：适合要对外发布、要精细控制视觉、甚至要做成产品宣传图的场景，但一般项目的内部文档用不到这么重。
这些工具之间没有绝对的优劣，我见过有人用 PPT 也画出了非常清晰的架构图。真正拉开差距的，是画图的人有没有想清楚结构和层次，而不是他打开的是哪个软件。我个人的做法是：快思考用 Excalidraw，落文档用 Mermaid 或 draw.io，面对多个团队对齐、需要反复修改的图用 draw.io。
3.2 动笔前 30 分钟：列要素、画边界、标受众
很多人的画图流程是“打开画板就开始拉框”，我不建议这么干。现在我的画图流程，前 30 分钟根本不开软件，而是拿纸笔做三件事。
第一件事，列出所有需要出现在图里的业务要素。拿“下单后完整链路”这个例子来说，我会列出：用户端、Nginx 网关、订单服务、库存服务、支付渠道、消息队列、数据库、定时任务，以及下游的物流系统。这一步只列名词，不管关系。
第二件事，明确这张图的边界。比如这次我们主要想讲清楚“下单到支付回调”这一段，库存锁定和物流订阅可以先虚化处理，边界外部的东西要么折叠、要么用一个大方框统一表示“外部系统”。
第三件事，写下一句图的核心结论或者题目。我们这次图的结论是“下单请求经过网关进入订单服务，先锁库存再接支付渠道，支付结果通过消息队列异步回调订单状态”。有了这句话，画图的每一步都可以回头校验：这个节点有没有服务于这句话，没有的节点就是多余的。
3.3 动手画三步：先主干、再加分支、最后补标注
准备工作做完，真正画图的时候我通常按照三步走。
第一步，先画主干路径。从用户点击“提交订单”开始，到订单状态变成“已支付”，把最核心的五六个节点先拉出来，用箭头串起来。这个阶段不要纠结布局，重点是链路完整、方向清晰。很多人一上来就画了一堆模块框，反而把主干淹没了。
第二步，再画分支和异常路径。比如“库存不足怎么办”“支付超时怎么处理”“消息积压时如何补偿”，这些分支在主干两侧展开。这一步最容易失控的地方是分支太多，我的建议是只画系统当前已经实现或者明确要实现的异常分支，千万别把“未来可能”的分支全部铺开，那不是画架构图，是在画科幻小说。
第三步，统一加标注和颜色语义。核心节点用深色突出，次要支撑组件用浅色，外部系统的统一用一种灰调并标注“外部依赖”。给关键箭头补充上文字说明，比如“HTTP 调用”“异步消息”“定时拉取”，这样一张图的语义才算完整。
3.4 从静态图到“活文档”：让图跟上版本节奏
一张图画完只是开始，真正让图和项目一起保持生命力的，是维护机制。我见过太多团队，架构图画得极其精致，但半年后系统已经改了三轮，图还停在半年前，新来的同学照着图找服务，怎么都找不到。这种“过期图”比没有图更害人。
让图保持新鲜的几个有效手段如下：
- 把图文件存进代码仓库，至少和文档放在一起，不要散落在个人网盘或者聊天记录里。
- 大的架构调整走评审时，把图更新作为合入条件之一，改代码的人有义务同步改图。
- 图的标题或者备注里写上“最后更新时间”和“维护责任人”，没人维护的图不如删掉。
- 如果用的是 Mermaid 这类文本图，可以在 CI 里加一步渲染检查，防止图语法坏了或者文件被误删。
4. 图表设计避坑指南：那些年我们踩过的坑
踩坑经验是比方法论更值钱的东西。下面这些坑，我几乎都在真实项目里遇到过，每一条背后都有一段“如果当时有人提醒我就好了”的感慨。
4.1 常见的六类翻车现场
| 现象 | 背后的原因 | 修改思路 |
|---|---|---|
| 图里字小到要放大镜 | 想在一页里塞下整个系统 | 拆成多层视图，一张图只讲一个层级 |
| 线条交叉成毛线团 | 布局没有规划，节点随意摆放 | 先列主干，再围绕主干排布分支 |
| 颜色五彩斑斓 | 用颜色代替层次表达 | 限制到 2-3 种语义色，其余用黑白灰 |
| 箭头方向不统一 | 一会儿从上到下、一会儿从左到右 | 全图统一主方向，折线尽量少拐弯 |
| 缩写、黑话满天飞 | 默认读者和你拥有相同背景 | 遇到专业缩写首次出现时加括号注释 |
| 和图完全对不上现状 | 图是一次性产物，没人维护 | 存仓库，设责任人，和评审流程绑定 |
这几类问题不是孤立的，往往一个问题会引发另一个问题。比如为了塞更多内容而缩小字号，最终可读性下降，评审效率变低，于是有人重新画了一张“简化版”，结果简化版和原来的版本不一致，又制造了新的混乱。所以画图的每一步都要克制。
4.2 一次架构评审会开崩了，问题不在口才，在图上
我想分享一个具体的复盘案例。有一次我们团队给一个外部协作系统设计方案，评审会前负责的同事花了大半天画了一张“高清全景图”，把涉及的十几个服务、所有对外接口、每一个数据库表都画了上去。PPT 翻到那一页时，全场安静了几秒，然后问题像连珠炮一样砸过来：“订单服务和支付服务之间的箭头是同步还是异步？”“这个虚线框是不是临时加的？”“为什么数据库有两个，它们之间什么关系？”
其实那位同事准备得非常充分，每个问题他都能答上来。但因为图里信息太密，大家的第一反应不是顺着他的思路走，而是被各种细节带走，会议讨论彻底绕进了局部细节里。复盘的时候我们都意识到：那张图不是画错了，而是用错了场景。它适合作为“详细设计文档”里的附录，但不适合作为评审会的开场图。评审会需要的是先给一张极简概览图，把核心链路亮出来，大家在大方向上对齐后，再逐层放大细节。
从那以后，我们团队定了一个不成文的规矩：评审 PPT 里的第一张图，节点数不许超过七个。超过七个，说明主讲人还没想清楚这一环节到底要让大家看什么。
4.3 三个让我越画越轻松的习惯
最后分享几个帮助我持续把图画好的小习惯，这些细节可能是很多教程不会提到的。
第一个习惯是“画完不马上发”。每次画完图，先去干点别的，过一两个小时再回来看一遍。这时候你很容易发现自己之前忽略的问题：某个箭头语义不清、某个节点名字不统一、某个分支逻辑和代码不一致。新鲜的视角是最好的校对员。
第二个习惯是“看图不加密度盲”。拿到别人的图，不要直接说“太乱了所以我不看了”。试着帮他把重点摘出来，说“如果我理解得没错，从 A 到 B 是主链路，C 是做兜底的，对吗？”很多时候对方会恍然大悟，然后自己动手改图。教会别人画好图，比替他改图更重要。
第三个习惯是“给图编号”。不管是文档里的插图还是评审用的图，都给一个唯一编号，像“图 3-2 订单超时状态流转”，这样在讨论时大家可以快速定位，避免“你往上翻一点，那张好多框的图”这种低效沟通。这也是在培养团队把图当成正式资产对待的潜意识。
做了这么多年 diagram-design 相关的事情，我越来越觉得，画图的本质不是“输出一张图片”，而是“训练自己和团队把复杂问题想清楚”。能画出一张好图，说明你已经把系统结构、关键路径和边界条件都梳理通了。反过来，图一直画不清楚，大概率不是工具的问题，也不是天赋的问题，而是某些关键点还没想透。下一次当你打开画板之前，试着先停下来问自己一句：这张图，到底想替我说清楚哪句话？想清楚了再动笔，你会发现画图这件事，突然就顺了。
