把画图当工程来做：一套可落地的技术制图规范与避坑指南

1. 复盘 diagram-design：我为什么把画图当成工程来做

diagram-design 是我沉淀了大半年的技术制图规范。它不是一个画图软件，也不是某个框架里的自动生成插件，而是一套面向技术文档、架构评审、故障排查和新人培训的“画图方法论”。过去团队里每个人都会画图，但画出来的东西风格各异：有人用圆角矩形，有人用直角矩形，有人把数据库画成圆柱，有人把数据库画成桶，箭头颜色更是五花八门。图一多，大家就开始互相问“这个框代表什么”“这条虚线什么意思”，沟通成本比写代码还高。

我用 diagram-design 想解决的，就一个问题：让一张技术图在没有任何口头解释的情况下，也能被团队里所有人用同一种语言读懂。同时它也要能适配文档、幻灯片、白板、代码仓库这些不同的展示场景，既能表达复杂系统，又不会让看图的人一头扎进细节里出不来。

如果你也在做方案设计、技术选型输出、组内分享，或者要长期维护一套系统架构文档，那我建议你先别急着拖组件。先把画图这件事当工程来做，你后面省下的解释成本会非常可观。这篇内容适合后端、前端、运维、大数据方向的开发人员，也适合需要画流程图、时序图、网络拓扑图的产品和技术写作者。

1.1 一张图被反复修改背后的真实原因

先说一个真实场景。某次做架构方案评审，我提前准备了一张服务依赖图。在线评审的时候，一位同事问：“这个灰色框是已有的服务，还是这次要新建的？”另一个人问：“从网关到订单服务的箭头是同步调用还是异步事件？”我当时一一解释，但评审完我发现，这张图脱离了讨论现场，没过几天就再也没人看懂了。

这就是大多数技术图的通病：画图的人脑子里带着完整上下文，默认看图的人也懂这些上下文。但实际看图的人往往只看图，不看你脑中那些默认。于是图越改越复杂，最后变成了只有作者本人能读懂的“密码图”。这个经历让我意识到，制图必须先定义信息语义，再考虑排版和配色。语义不一致，再好看的颜色都是噪音。

1.2 diagram-design 交付什么内容

diagram-design 实际沉淀下来的是四类东西：一份符号语义表、一套布局规则、一组可复用的模板、一张评审自查清单。它不强求你用某个特定工具，而是要求所有产出物遵循同一套信息表达规则。因为工具可以换来换去，但底层逻辑如果不统一，换工具只会把混乱搬个家。

符号语义表解决“框和线代表什么”，布局规则解决“信息怎么排布更不容易读错”，模板解决“不同场景下的图应该长什么样”，评审自查清单解决“画完之后怎么确认自己没有自嗨”。这四样东西组合起来，就是一套可以长期维护的制图基础设施。你可以把它放到团队文档库，或者跟着代码仓库维护，每次更新时走版本记录。

1.3 不同场景的图要有不同优先级

我最早犯的错，是想用一套规则约束所有图。后来发现架构图、流程图、拓扑图、时序图各自的目标不一样，不应该完全同构。架构图重点看组件边界和依赖关系，流程图重点看分支和异常路径，拓扑图重点看网络连接和部署位置，时序图重点看消息顺序和生命周期。diagram-design 对它们只约定底层的通用语义，再为每种图扩展出针对性规则。

画图前先确认这是哪一类图，比先选择什么配色重要得多。方向错了，形式做得再精美也没有价值。

2. 拆解核心思路：先定信息骨架，再谈视觉表达

diagram-design 的底层思路其实非常简单：把所有技术图都当成“信息结构”来设计。视觉只是信息的载体，如果信息结构没有梳理清楚，后面所有排版技巧都只是装饰。我一般把设计流程分成三块：先回答决策问题，再拆信息层级，最后才进入符号和布局。

2.1 动笔前先回答三个问题

我每次画图前都会在文档顶部写一句话，类似“这张图用来让新同学在 10 分钟内理解订单创建的主链路”。写不出来的话，说明连我自己都不知道这张图到底要传递什么。三个固定问题分别是：给谁看的？看完之后他需要理解什么或做出什么判断？这张图会出现在哪里？

这三个问题直接决定信息取舍。给新同学看，就要把核心链路画得粗一些，把容灾细节折叠起来；给稳定性评审专家看，就要把超时、重试、降级路径放上去。出现在幻灯片里，文字要少，字体要大；出现在代码仓库的说明文档里，可以多放注释，但不要用太密的布局。场景不同，同一套系统可以拆成好几张图，而不是硬塞成一张“全家福”。

2.2 信息分层：主链路、辅助链路、上下文

设计图的时候，我把信息分成三层。第一层是主链路，它是图里的主角，视觉上要最突出；第二层是辅助链路，比如缓存、异步通知、日志上报，它们围绕主链路存在；第三层是上下文，比如外部系统、部署边界、用户入口，用于帮助读者定位。这三层不是并列关系，而是按视觉权重递减的关系。

实际操作时，我会先用文字把主链路写出来，比如“用户请求经过网关，转发到订单服务，订单服务写库后发送事件，通知服务消费事件并短信通知用户”。主链路成立之后，再把缓存、重试、监控这些辅助链路挂上去。最后补上下文边界。这个顺序保证了图画出来不会变成一团乱麻，因为你的视线始终有一条主线可以跟着走。

2.3 符号语义，统一到一张图例上

diagram-design 里最核心的，是那张符号语义表。没有这张表，每个框都要靠标签说明，图永远干净不了。我采用的规则尽量少而明确：圆角矩形表示当前系统内的服务或模块，直角矩形表示外部系统或第三方组件，菱形表示判断分支，圆柱表示数据存储，虚线框表示部署边界或逻辑分组。箭头方面，实线箭头表示同步调用，虚线箭头表示异步事件或消息，粗箭头表示这条路径是主链路。

这套规则的好处是，它不依赖工具，也不限制创意。任何人拿到一张符合规范的图，先看图例和主粗箭头，就能抓住骨架；再顺着实线虚线把细节补齐。注意不要在同一张图里堆满十几种形状，那样等于没有规则。为了表达某些特殊含义，你最多增加一两种扩展符号，而且必须画进图例区。

2.4 布局法则：方向、对齐、交叉

布局是大多数人画图时最容易失控的地方。diagram-design 定了几条硬性法则：整张图只能选择一个主导方向，要么自上而下，要么从左到右，不允许东一块西一块地乱放；所有节点尽量对齐到网格上，不要出现莫名其妙的居中漂移；连线尽量走正交路径，少用斜线；同一条线上的箭头要统一方向，不能一会儿向右一会儿向左。

为什么这么较真？因为人的视线在水平方向和垂直方向上的移动成本最低。方向统一时，读者可以用扫描的方式理解图，而不是来回跳着寻找顺序。连线交叉是最大的阅读障碍，尽量减少交叉，哪怕因此需要重复出现同一个节点。重复节点配合虚线框引用，也远好过一团剪不断理还乱的连线。

3. 实操流程：从需求到终稿的五步法

纸上谈兵没有用，我把自己常用的完整流程拆成五步。这套流程不用额外开发工具，完全靠习惯就能跑起来。你现在就可以拿一个真实项目试一次。

3.1 工具与交付形态怎么选

工具选择会影响效率，但不应该影响规范。diagram-design 里只有两类工具定位：一类是所见即所得的矢量画板，适合做演示图和精细排版；另一类是文本化图表语言，适合把图的源文件放进代码仓库，走版本管理和多人评审。两种形态各有取舍，我一般用表格来决定每次用什么。

我的习惯是：临时画个草图用白板，正式沉淀进文档库的图尽量用文本化描述。因为长期维护的图迟早会被改，文本形式让改动记录、责任边界都变得非常清楚。

3.2 五步法具体操作

第一步，写需求笔记。用三句话说明给谁看、看什么、放哪里。这一步不能跳，哪怕只花两分钟。第二步，画信息骨架。先在纸上或白板上用最简单的方框和箭头把主链路画出来，完全不管排版和颜色，只确认“有多少个节点、多少条关键路径”。骨架阶段如果节点超过十五个，就考虑分层拆图。

第三步，套模板和符号语义。把骨架里的方框替换成规范形状，把箭头替换成实线、虚线或粗箭头，给数据存储加上圆柱符号。第四步，做布局与标注。确定方向和网格对齐，加上图例、标题、版本和一句摘要说明。第五步，评审修正。找一个人对你的图做“无讲解阅读”，他读不懂的地方就是你要改的地方。这五步看起来笨，但恰恰是它保证了最后产物的可读性。

3.3 一个订单链路图的落地示例

我拿一个最常见的订单创建链路来演示。需求笔记很简单：给新同学看，理解一次下单请求的主链路，放在系统文档首页。信息骨架画出来后，文本示意大概是这样：

[用户] --HTTP--> [接入网关] --RPC--> [订单服务] --SQL--> [订单库] | +--MQ事件--> [通知服务] --短信--> [用户]

对照规范，我把外部用户画成直角矩形，网关、订单服务、通知服务画成圆角矩形，订单库画成圆柱。HTTP 调用和 RPC 调用画实线箭头，MQ 事件画虚线箭头，核心链路加粗。辅助链路比如“日志采集”和“监控告警”并不放上这张图，而是单独拆成一张可观测性图。最终图里没有多余颜色，主链路一种强调色，辅助链路统一灰色，图例放在右上角。

这样落地之后，新同学看文档时不再需要到处问人。他先看图例，再顺着粗箭头读一遍，就知道订单服务是整个链路的核心，数据库写入和 MQ 事件是紧随其后的关键动作。一张图能够独立完成这个使命，就不辜负它占据的那块文档版面。

4. 核心细节与避坑技巧：颜色、文字、连线

有了清晰的骨架，剩下的就是细节。很多图画得丑、读着累，不是信息问题，而是颜色和排版的细节出了问题。这部分我把实践里最有用的几条写下来，都是常规文档里不太会提的。

4.1 配色越克制越专业

一张技术图里，颜色承担的是分类功能，不是装饰功能。diagram-design 默认采用“灰底 + 一种强调色 + 语义色”的配色方式。所有普通组件用浅灰填充加深灰描边，主链路或者核心组件用一种强调色，只有表示异常、危险、阻断的时候才用红色这类高饱和语义色。绿色尽量少用，因为它和“成功”绑定得太紧，不是所有读者都有同样的语义预设。

配色还要考虑色弱读者。不要用红绿作为唯一区分方式，红色组件除了颜色外，最好再加粗边框或者在标签里加“故障”这样的文字前缀。深浅色背景下也要验证对比度，深色模式下不要使用大面积深蓝配黑字，浅色模式下不要大面积使用亮黄底。我通常会在导出前切到深色背景预览一遍，确认连线不会被背景吃掉。

4.2 文字排版和留白

节点里的文字要短，最好不超过六个字。无法缩短时，把完整的名称写进图例，图上只留缩写。字号尽量统一，不要把标题、模块名、注释堆成三种大小互相干扰。文字对齐要么全部居中，要么全部左对齐，不要同一个框内一个居中一个靠下。斜体和下划线尽量避免，因为容易把文字和超链接混在一起。

留白是很多人忽略的维度。节点与节点之间保持足够间距，不要让边框贴在一起；连线上不要放太多文字，必须标注时，把文字放在线的中间上方，并且给文字加一层背景色，避免和连线重叠。图里的信息密度宁可低一些，也不要为了一页放下更多内容而牺牲可读性。

4.3 连线端口与折点

连线画得是否专业，看两个地方：起点终点接在哪儿，以及折点是否干净。节点通常有四条边的中点可以作为端口，连线尽量从边的中间进出，不要从任意角落斜插进去。如果两个节点之间有多个连线，要保证所有连线从同一侧进出，避免一条从上面走，一条从下面绕，最后乱成一团。

折点数量越少越好。正交折线每增加一个折点，阅读负担就增加一分。有些图工具会自动布局，但它并不理解业务语义，所以我自己偏好先手工摆好节点顺序，再让工具按网格自动整理。当出现长距离连线时，宁可多放一个“重复节点”做转折，也不要让一条线横穿整张图去跨越多个无关组件。

4.4 把图例做成图的一部分

图例不是可选项。我见过很多图，画得非常精细，却没有图例，结果每个读者都在猜灰色虚线框到底是什么。diagram-design 要求图例必须直接出现在图内，而不是写在文档正文里。图例区放在右上角或左下角，占的位置不需要很大，但要包含所有使用到的形状和箭头样式，并且加上一句简要说明。

图例还要配合摘要文字。我会在图下方加一行，比如“本图展示订单创建主链路，虚线表示异步消息，红色框表示异常场景节点”。摘要文字比图例更进一步，它直接告诉读者“这张图怎么看”。有了它，即使读者完全不了解项目背景，也能在一分钟内进入状态。

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

实操过程中，我踩过的坑基本都能归到下面几类。这里面有些问题是工具层面就能解决的，有些必须回到信息层面重新思考。

5.1 图又满又密怎么办

图太满，通常不是因为内容多，而是因为一张图试图承载太多目标。我不建议靠缩小字体、压缩间距来硬塞，正确做法是拆图。把大图拆成“总览图 + 细节图”：总览图里只保留模块边界和主要依赖，细节图里再展开每个模块内部流程。两图之间用相同的模块命名和编号互相引用，读者先看总览，再按需点进细节。

拆图时要注意维护索引。每张细节图都要明确标注“这是总览图中第几号模块的内部实现”，否则拆完之后读者反而找不到上下文。实务上我会用编号分组，比如 A 组是接入层，B 组是业务层，C 组是数据层。总览图里的 C-2 走进去就是对应的数据层细节图。这样图的数量变多了，但单张图的负担变轻了。

5.2 连线交叉怎么都排不掉

交叉线的本质是节点顺序没有配对好。大多数情况下，把上下游节点按照“调用发起方在上游，被调用方在下游”的顺序重新排列，交叉就会减少。如果还有交叉，看看能否让多条连线走同一条“总线”，比如统一经过消息队列或网关再分发。总线表达真实业务上的汇聚点，同时也顺带解决了视觉杂乱。

另一种有效技巧：把同一层的节点放在同一个水平带内，让连线只在相邻带之间出现，不要跨越多个带。如果两个节点距离非常远，说明它们在架构上很可能不该直接耦合。这时候与其调整连线，不如回头问问业务上是否真的存在这条直连路径。图不好画，往往是架构本身绕了路。

5.3 团队成员不按规范执行

规范落地最大的阻力不是理解，而是习惯。为了解决这个问题，我把 diagram-design 做成了一张“一页速查表”和一批模板——而不是几十页手册。团队成员第一次画图时，只要复制模板改内容，格式就不会跑偏。评审时我只看自查清单，不啰嗦个人偏好。清单里全是客观检查项：图例是否齐全，是否只有一个主导方向，主链路是否加粗，有没有超过三种强调色。

如果还是有人不遵守，多半是因为模板不够好用。这时候不要怪人，要去更新模板。规范是给人用的，如果它让画图变得更慢，那迟早会被抛弃。好的规范应该让最简单的一次画图也直接达标。

5.4 快速自查清单

自查清单会让每个人在导出图之前冷静十秒钟。我实测下来，这一张表比任何制度都管用，因为它的判断标准足够客观，团队评审时不容易吵起来。

5.5 图被复用后失去上下文

很多图第一次画的时候效果很好，三个月后打开却没人看得懂。原因是没有记录上下文。我后来在每张图的源文件头部固定写一段注释，包含三个信息：这张图给谁看、当前版本解决了什么问题、下次修改时需要重点确认哪些假设。这些注释不进入最终展示，但对维护者来说是救命信息。

文档里的实际展示位置也会影响理解。图不要孤立地挂在页面中间，前后至少要各有一句话交代背景。如果一张图属于“故障排查专项”，就在图下方说明触发条件是什么，看完图下一步该做什么。读者带着任务来看图，比被丢进一张陌生系统图里的体验要友好得多。

6. 踩过这些坑之后，我最想保留的三个习惯

把个人经验沉淀成规范的过程里，我留下三个反复验证有效的习惯。它们不是多复杂的技术，但长期价值非常高，分享出来供你参考。

6.1 每张图只留一个主角

复杂系统里处处都是信息，但一张图只能有一个核心信息。画图前我会问自己：如果读者只能从这张图里带走一件事，我希望它是什么？这件事就是主角。主角用粗边框或高亮色突出，其他所有内容围绕它展开。没有主角的图，读起来就像没有重点的会议，散场后什么都不记得。

我在重构某个系统的架构图时，最初把十几个微服务全画上去，每个服务都用不同颜色，结果评审时大家各看各的，谁也说不清重点。后来我把图分成三张：一张讲“流量如何进入系统”，主角是网关；一张讲“订单状态如何流转”，主角是状态机；一张讲“数据如何落库”，主角是存储层。每张图主角清晰，评审效率立刻上来了。

6.2 把图当成会进化的代码

技术图不是交付的一次性产物，它和代码一样需要持续维护。所以我更倾向于使用文本化图表语言来保存正式图，让每次改动都可以 diff、可以回滚、可以留提交说明。团队里任何人想改图，不是直接编辑一张图片，而是修改源文件并触发评审。这样图的演进过程会被完整记录，也不会出现“文档里那张图已经和线上系统完全对不上”的失控状态。

我最开始也觉得这个习惯有点重，直到某次排障时需要确认某个模块是哪个版本引入的依赖。因为图源文件里有完整的提交历史，十分钟就定位到了变更记录。这个效率提升，让我坚定了“图也能走代码评审”的思路。

6.3 保持 30 秒读懂的标准

一张经过 diagram-design 处理的图，应该达到一个硬指标：一个对这个项目完全陌生的人，看它 30 秒后，能用自己的话复述出主链路和关键依赖。达不到就继续改。这个标准听起来苛刻，但很有效。它逼着我把最想表达的信息放到最显眼的位置，把不重要的细节收进折叠区，把含糊的箭头改成明确的语义。

我现在画完图之后，习惯找身边的同事做一次“30 秒测试”——只让他看图，不做任何解释。测试结果几乎总是指出我之前没想到的模糊点。这个动作做多了，画图的时候就会自然提前把容易误解的地方处理干净。时间长了，团队里的图会慢慢形成一种统一的“呼吸感”，哪怕不看署名，也能一眼认出这是按同一套规范画出来的。这就是 diagram-design 真正想达到的状态。