技术图表设计之道：从拍脑袋画图到图即代码的工程化实践

有段时间我特别烦一件事：每次有人问我某个系统的整体结构，我得现场翻代码、查依赖、在白板上画十来分钟，画完了对方还一脸茫然。后来我开始认真琢磨diagram-design这件事——它说的不是把线画直、把框对齐那些细枝末节，而是把“画图”从拍脑袋的即兴发挥，变成一个有方法、有规范、能评审、能持续维护的设计过程。这篇文章把我这一年的思考、工具选型和踩坑记录都整理出来，适合正在整理技术文档的开发者、需要给团队画架构图的负责人，以及任何被“一张破图画三天”折磨过的人。

我见过太多图表的“死法”：画完没人看，看了看不懂，看懂想改却根本改不动。问题几乎都不出在绘图软件上，而出在动笔之前——你根本没想清楚这张图要替谁回答什么问题。所以这篇文章我不会只教你怎么操作某个工具，而是从“图到底是给谁服务的”聊起，再把图表类型选择、图即代码的工程化、实际落地流程和长期维护串成一套可以照做的体系。

1. 为什么给系统画图这件事，本质上是设计而不是作图

1.1 技术图表最常见的三种“死法”

先说我观察到的三种典型情况，你可以对照自己的团队看是不是也这样。

第一种死法是图文无关。架构评审时贴了一张很漂亮的架构图，配色统一、图标精致，但里面的模块名跟代码里的包名对不上，服务之间的连线也早就是半年前的状态了。这种图贴在哪里都只会误导人，所以大家干脆不看。

第二种死法是信息过载。一张图上塞了三十几个节点、几十条箭头，还标注了端口号、协议、缓存策略、限流阈值。乍一看觉得“好全”，仔细看两眼就开始头疼——因为眼睛不知道先看哪里，脑子更记不住那么多东西。这种图往往只服务了画图者自己的表达欲，没有服务读者的认知节奏。

第三种死法是改不动。图是用拖拽工具一笔一笔拉出来的，节点间距、箭头拐弯全靠手工微调。等架构真变了，改一个框要重新排半天的版，最后只能咬咬牙“下次再统一更新”，然后就再也没有下次了。

这三类问题表面上是执行力、表达力、工具链的问题，本质上都指向同一件事：你还没有把画图当作一个需要设计的过程，只想快点交出一个“画完的东西”。

1.2 diagram-design 拆开看：信息结构、抽象层级、视觉表达

我给 diagram-design 下的定义是三件事的组合：信息结构设计、抽象层级设计、视觉表达设计。

信息结构设计指的是：这张图里必须出现哪些实体，实体之间的关系是什么。这是图的骨架，决定了图画完是不是“对”的。比如你画下单链路，至少要有用户、订单服务、库存服务、支付服务这几个实体，以及它们之间的调用和返回关系。

抽象层级设计指的是：这张图站在什么高度看系统。站在运维视角，你要画物理部署和网络分区；站在业务视角，你要画领域服务和业务流程；站在代码视角，你要画模块和类。同一个系统，不同高度画出来的图完全不一样。

视觉表达设计则是最后一步：把结构画成什么样的布局、用什么样的颜色、箭头怎么走、标题怎么起。很多人把精力全花在这一层，前面两层却完全没想，结果就是做出了漂亮的垃圾。

所以我在动手之前，总会先逼自己回答两个问题：这张图是给谁看的？他想通过这张图做什么决策？目标一旦明确，后面的类型选择、内容取舍、画法风格其实都会顺理成章。

1.3 先定位“读者”和“决策场景”，再谈画什么

拿一个具体的例子来说。同样是一个订单履约系统，下面四类人需要的图完全不同：

• 新入职的同事：需要一张系统全貌图，知道有哪几个核心服务、每个服务的职责边界是什么；
• 线上排查问题的值班工程师：需要一张请求链路时序图，看清楚一次下单调用先后经过了哪些服务，哪一步可能失败；
• 要做容量评估的负责人：需要一张部署架构图，看清每个服务部署了几台实例、流量入口在哪、存储怎么分片；
• 要做数据治理的数据工程师：需要一张实体关系图，看清楚订单、支付单、库存流水这些模型怎么关联。

如果不管三七二十一，只想画“一张架构图”去满足所有人，结果一定是每个人都不满意。diagram-design 的第一步不是打开画布，而是列出读者清单和决策清单，然后决定这一批要产出的是一组图，而不是一张包罗万象的图。

这也是很多人忽略的点：同一个系统通常需要一组图配合使用，单张图的正确角色是“讲清楚一个主题”，而不是“威胁把所有信息都装下”。想清楚这个，后面每一张图都会好画很多。

2. 按场景选图型，别指望一张架构图扛下所有问题

2.1 高频图表类型与各自的适用边界

我整理了自己日常最常画的几类图，不是 UML 全部图纸，而是工程技术文档里出现频率最高的几种。

系统架构图：描述组件构成和它们之间的静态关系，适合回答“系统由什么组成、谁依赖谁”。这种图最常见的错误是节点太多、箭头太乱，所以我给自己定的规则是：只有直接相关的组件才上同一张图，间接依赖关系用文字或链接带过。

时序图：描述一次跨模块交互的先后顺序，适合回答“一次请求经历了什么、失败了会影响什么”。画时序图时最容易漏掉的是超时、重试和异步回调，这些恰恰是排查问题最关心的部分。图上一定要把那几条“非主路”画出来，别只画理想路径。

数据流图 / ER 图：前者描述信息的流转与加工，后者描述业务实体之间的关系。适合回答“数据从哪来到哪去、库里有什么、怎么关联”。这类图一旦达到十几个实体就非常难排，我通常按业务域拆成多张子图。

部署拓扑图：描述服务实例、网络分区、中间件和数据存储的物理分布，适合回答“服务跑在哪、故障可能出现在哪”。画这种图务必把机房/可用区、公网入向、内网调用分层表达清楚。

把这些图型放在一张对照表里看更直观：

2.2 不同受众看不同图：把“受众-图型”映射落到文档体系

光知道图型还不够，下一步是把受众和图型映射到文档体系里。我在整理项目文档时，习惯给每类文档固定配图，避免文档更新时漏图：

• 系统 README 至少配一张系统架构图，让新人在三分钟内建立全局认知；
• 接口文档配时序图，说明一次调用的完整链路；
• 数据库设计文档配 ER 图和关键表关系说明；
• 运维手册配部署拓扑图，并把告警入口、日志位置写在图注里。

这个映射关系一旦固定下来，团队写文档就会形成惯性：新建服务必须补架构图，新增接口必须补时序图，变更表结构必须同步 ER 图。图不再是“有空再补”的可选项，而成了交付的一部分。

2.3 一张图一个主题：切分而非压缩

新手最容易犯的错是试图压缩。他们会觉得“我把架构图、时序图、部署图画在一张大图里，不是更全面吗？” 但人眼的处理能力是有限的，信息密度超过一定程度后，理解成本指数级上升。

我的经验是：与其压缩，不如切分。一张图超过十个核心节点，立即问自己能不能拆成两张。例如一个系统从下单到履约的完整链路，可以先画一张粗粒度的“系统总览图”，再分别画“下单时序图”和“库存扣减时序图”。总览图给读者挂图索引，分图给读者具体细节，两者配合刚好。

这不只是美观问题，更直接影响维护成本。十一个节点的图，改一个节点可能要动五个箭头；拆成两张六节点的图，每次改动范围小得多，review 的人也轻松得多。这正是 diagram-design 和普通画图的第一个分水岭。

3. 图即代码：把图表纳入版本库、评审和自动化的那套工程玩法

3.1 为什么我放弃了纯手工拖拽绘图

我从 Draw.io 用到了 Excalidraw，坦白说这些工具做临时沟通图非常顺手。但它们有一个绕不开的问题：图一旦进了位图或二进制文件，就失去了代码的几乎所有优点——不能 diff、不方便 review、没法脚本化校验、难以复用模块。

举个例子，我用拖拽工具画了一张架构图，过了俩月架构改了三个地方。我改完一个框，另一个框的相对位置也歪了，还得手动排。这个过程中发生了哪些改动？说不清楚。review 时审核的人只能看到“图变了”，但具体是连线变了还是节点换了，几乎无从对比。这对严谨的架构评审是很伤的一件事。

后来我转向了图即代码（Diagram-as-Code）的路线：用纯文本描述图的结构，再交给渲染引擎生成图片。这样图就跟代码一样进 Git 仓库，每次改动有 diff，评审可以针对具体行进行讨论，还能用脚本检查孤立的节点、缺失的图例。尝到这个甜头之后，我再也没有回去老老实实拖过一张正式文档用的图。

3.2 文本化图表工具怎么选：Mermaid、PlantUML、D2 的取舍

市面上图即代码的工具不少，我实际用过三条路线，简单说说各自的脾气。

Mermaid的语法最接近自然语言，画流程图、时序图、状态图都很快，学习成本几乎为零。它对 Markdown 生态友好，很多文档平台直接支持渲染，适合“顺便记录一下流程”这种场景。缺点是复杂 UML 类图支持较弱，大型架构图的表现力有限。

PlantUML在 UML 领域更正统，尤其画类图、用例图、部署图时语义更严谨。它的语法表达力很强，但学习曲线比 Mermaid 陡一些，官方皮肤样式也偏“工程风”，需要顺手做一点样式配置。

D2是后起之秀，语法比 Mermaid 更干净，布局引擎在复杂图中更聪明，尤其适合画服务依赖图和网络拓扑图。我最近几个项目开始用 D2，整体体验很稳，唯一的顾虑是社区规模相比前两个还小，遇到偏门问题能查到的资料少一些。

我给一个相对中庸的选型建议：日常文档、团队协作选 Mermaid，UML 体系严格建模选 PlantUML，依赖关系复杂、对布局要求高的架构图试一下 D2。工具不用追求“世界上最好”，要选“团队里大多数人愿意用且能用好”的那个。

3.3 把图放进代码仓库后，diff、评审和渲染怎么跑

文本化只是第一步，真正的工程化体验来自配套流程。我现在维护的项目里，图的目录结构大概是：

docs/diagrams/ ├── src/ # 图源码：.mmd / .puml / .d2 ├── out/ # 渲染产物：svg / png └── README.md # 图索引和更新说明

源码提交进仓库后，CI 里会跑两步：第一步用固定版本的渲染引擎，把 src 下所有图源渲染成 SVG 产物；第二步跑一个简单的校验脚本，检查所有 .md 文档里引用的图文件是否真实存在、图内是否有没有连线的孤立节点、是否带了图例和图注。渲染产物不进 review 的重点，review 的重点永远是源码 diff。

评审环节我坚持“图跟代码同 PR”。哪次需求改了接口，就必须在同一分支里把对应的时序图同步更新，否则 PR 打回去。这样做好处非常明显：图的更新节奏跟代码完全绑定，再也不会出现“图还是上个月的、代码已经是这个月”的离谱情况。等跑了两三个迭代，团队会自然形成条件反射，画图就成了一项跟写注释一样的日常事务。

4. 从白板草图到一套图表规范：模拟项目X的完整落地过程

4.1 背景：一个订单履约系统的图表体系为什么要重做

为了让你能直接照搬流程，我拿一个虚构的“模拟项目X”当作例子。这是一个订单履约系统，有用户服务、订单服务、库存服务、支付服务、物流服务五个核心模块，外加消息队列和缓存中间件。

之前团队的文档里只有两张手工画的架构图，已经半年没更新。新来的同事问“订单状态都怎么流转的”，有人口头讲一遍，有人翻代码，讲得还不一样。刚好赶上要做一次整体技术方案评审，我借这个机会把整套 diagram-design 流程走了一遍。

4.2 三步走：先白板草图，再结构化，最后代码化

第一步，我拉了几个核心开发约了三十分钟白板讨论。白板阶段不追求符号规范和美观，就是画矩形、连线、写关键词。重点是把大家的共识对齐——哪个模块真的算独立服务，哪个只是内部功能；订单到履约的链路到底是先扣库存还是先生成订单；哪些地方存在异步回调。这些共识是图的灵魂，如果从代码里反推，很可能把过时设计当成既定事实。

第二步，把白板草图结构化。我重新画了一张系统总览图，定义出清晰的边界：对外入口、内部五个服务、依赖的外部支付渠道、消息队列和缓存。另起一张下单时序图，画出用户下单、校验库存、锁定库存、创建订单、调用支付、支付回调、通知物流的完整序列。再起一张数据 ER 图，把订单、订单条目、支付单、库存流水之间的关系理清楚。

第三步，把结构化草图转成文本代码。用 Mermaid 语法对应生成三份源文件，提交到文档仓库里。转型时间比想象中短，因为关键决策在白板阶段都做完了，剩下的只是技术翻译。

下面是用text标注的示意源码，展示下单时序图的样子:

sequenceDiagram actor 用户 participant 订单服务 participant 库存服务 participant 支付服务 用户->>订单服务: 提交下单请求 订单服务->>库存服务: 锁定库存 库存服务-->>订单服务: 锁定结果 订单服务->>支付服务: 创建支付单 支付服务-->>订单服务: 支付单号 订单服务-->>用户: 返回待支付订单

这套流程的关键在于决定先于绘制。白板阶段的产出是决策和关系，代码阶段的产出是决策的固化表达。很多团队跳过白板直接画正式图，结果画着画着才发现关系没定清楚，被迫返工，反而更慢。

4.3 命名、分组、着色和锚点：让整套图看起来像同一套系统

图即代码解决了维护问题，但“看起来像一套图”还缺一份轻量级规范。我给模拟项目X定了四条规则，简单到每个人都能记住：

命名规则：每张图文件名以类型前缀开头，如arch-system-overview、seq-order-create、er-order-domain。图内节点命名采用“模块名-功能名”，避免同一个节点在不同图里叫法不一致。

分组规则：围绕业务边界分组。以订单服务为例，所有跟支付相关的节点放在一个子图里，跟物流相关的放另一个子图。子图与子图之间只保留粗粒度的交互线。

着色语义：外部依赖统一用灰色，内部核心服务统一用蓝色，新增或变更节点统一用黄色高亮。规则一定要简单，并且必须在图注里写明色板含义，不依赖看图者靠猜。

锚点与图注：每张图右下角固定写“适用范围、维护负责人、最近更新日期”，并且图上必须能通过链接跳到对应代码目录。这样任何读者看到图，马上就能找到对应的代码和负责人，图的“活文档”属性立刻被激活。

这套规范听起来很基础，但实际效果立竿见影。新同事第一次接触项目文档时，只花五分钟就理清了订单履约的整体链路，而上一版文档他们要四处翻代码才能拼出来。

5. 图表腐化与排错：四个我真实踩过、后来定了规矩的坑

5.1 复杂度失控：图怎么越画越像蜘蛛网

我最早画架构图时有个坏毛病：总怕漏掉信息，把所有细节都堆上去。结果一张图出现几十个节点，线条互相交叉，看上去跟蜘蛛网一样。后来我发现，读者看这种图时普遍只会做一件事——发一句“这系统真复杂”，然后关掉页面。

解决这个问题的关键不是“少画一点”，而是在正确的抽象层级上画。我给自己定的硬性规则是：单张图主节点不超过十个；超过就立刻拆图。总览图只画服务和依赖的宏观关系，细节下放到分图。每拆一次，图的可读性就上一个台阶。这其实就是前面提到的 C4 分层思路的简化实践：一层管全景，一层管细节，两层互相引用。

5.2 图与代码脱节：文档漂移怎么根治

第二个坑是图和代码脱节。图更新慢半拍，代码已经重构了，图还在描述老结构。这个问题靠“自觉”是治不好的，必须靠工程手段。

我后来在 CI 里加了一个轻量校验：维护一份service-list.yaml，里面按规范声明服务名、职责、依赖方。CI 渲染架构图时，直接读取这份声明文件生成图的基础骨架，再叠加上少量手写的布局说明。这样一来，服务增删、依赖变化都会直接被 CI 发现，图不会静悄悄地烂掉。

如果你的项目暂时没条件做自动化，也可以退一步做人工约定：每周代码评审时，把相关图表作为 PR 检查项之一，不允许图与代码不同步。关键在于把“同步更新图”变成硬性交付要求，而不是可做可不做的善后工作。

5.3 工具链版本升级导致的图表“大面积瘫痪”

图即代码的工具迭代很快，但版本升级不一定向后兼容。我有一次升级渲染引擎后，夜间定时任务生成出来的图全部报错，原因是一个画节点边框的语法在新版本里被移除了。那次之后我总结了三条经验：

第一，锁版本。CI 和本地环境都使用固定的渲染引擎版本，升级动作要显式触发，而不是跟着依赖漂移。第二，固定渲染环境。比如用容器跑渲染，避免“本地能出图、CI 出不来”的尴尬。第三，升级前先做一次全量回归。把仓库里所有图源在新版本下渲染一遍，对比产物，确认没问题再换版本。

这类问题在手工拖拽时代不存在，一旦进入图即代码的体系就会经常遇到。但只要版本管理做得到位，可复现和可回滚反而成了巨大的优势——这在拖拽工具里是完全不敢想的。

5.4 团队里有人不认图：从工具问题到协作问题

技术问题解决后，更隐蔽的是团队习惯问题。总有人觉得画图是形式主义，浪费时间是“不如写代码实在”。我一开始硬推过一阵，效果很差。后来发现，与其讲道理，不如把图画的价值直接嵌进他们每天的工作流里。

具体做法是在方案评审时规定：方案文档必须带图，不带图不进入评审。所有人都得按图来讲自己的模块边界和交互方式。几轮下来，团队发现没有图根本说不清接口改动影响范围，画图的习惯就自然长出来了。另外，每张图指定一个 owner，谁负责这张图谁对它的更新负责，不设负责人就等于没设人管。

我最大的体会是：图这种文档形式，跟代码一样需要 owner 和评审机制。没有 owner 的图注定会荒废，没有评审入口的图注定会成为摆设。

6. 图的长期维护：把图表当作代码资产来管理

6.1 什么时候该更新图：触发条件比固定周期更靠谱

我见过团队定“每月最后一周更新架构图”，听起来很合理，实际上月底大家根本想不起来。后来我把触发条件改成了和代码变更强相关的事件：

• 新服务上线或服务下线时，必须更新系统总览图和部署拓扑图；
• 新增外部依赖或变更接口协议时，必须更新对应的时序图和依赖图；
• 表结构或领域模型变更时，必须更新 ER 图；
• 每次迭代发布前，图形文档的更新情况要作为发布清单的检查项之一。

固定周期容易让人产生“这是额外工作”的抗拒感，而把更新和图绑定进代码变更事件，图就变成了交付的一部分，不会被无限搁置。这是我从实践中得到的非常关键的经验：让图的更新跟着代码的节奏走，别让图自己去定单独的节奏。

6.2 我每次 review 图时都逐项检查的六条清单

把图画出来只是开始，真正保证图的长期质量在于 review。下面这份清单是我每次看别人图纸（也看自己图纸）时逐项过一遍的规则，你可以直接抄走。

这六条看上去很琐碎，但它们能挡住 80% 的图表腐化问题。比如命名一致性，很多图烂掉不是因为信息错了，而是因为服务叫法变了但图没改；方向与语义更是常见，箭头画反了直接误导所有人。

Review 图的频率不需要很高。我的习惯是架构评审和代码评审涉及图表变更时顺带检查，熟练之后一分钟就能完成一张图的检查。低成本高频次的检查，远比三个月一次“大规模整理文档”有效。

6.3 图演进记录：图表之间的引用关系也要维护

当图纸变多之后，还会出现一个新的问题：图之间的关联关系没人维护。系统总览图里提到的“见下单时序图”，但下单时序图其实已经改版过三轮，名称也变了。这会导致文档链接失效，读者又回到翻代码找信息的状态。

解决方法很简单：在docs/diagrams/README.md里维护一张图索引表，列清楚每张图的名字、用途、适用场景、最近更新日期和维护人，同时把图与图之间的引用关系写清楚。这份索引表本身就是 diagram-design 体系的地图，也是整个文档库的导航页。

维护图索引不需要额外工具，Markdown 表格完全够用。每次新增图或改图名，顺手改一下索引表，一分钟的事。但这个动作相当于给图纸体系上了一张总目录，长期价值远超投入——它让团队的文档在数量变多之后，依然开门见山、一目了然。

说到底，diagram-design 从来不是教你用某个工具，而是建立一套围绕“图”的思维习惯和协作制度：动手前想清楚读者和主题，画图时选对图型和控制密度，落库后让图跟着代码走、跟着评审走，最后用一份轻量规范让整套图长期保持一致性。我自己按这套方法把模拟项目X的文档体系重做之后，最直观的感受是：新同学上手快了，方案评审少吵了，改需求时想哭的次数也少了。如果你现在正被一堆画完没人看、看了不想改的技术图困扰，不妨从下一个小需求开始，只补一张时序图，试一次“图与代码同 PR”，应该会很快体会到差别。