图即代码：用Mermaid打造可维护可评审的技术设计图

最近在 GitHub 上注意到一个仓库，名字叫 cathrynlavery/diagram-design。仓库本身可能只是个人作品集或兴趣项目的起点，但 diagram-design 这个组合词很值得停下来想一想：我们天天用 diagram 表达系统架构、业务流程、接口时序、数据模型，但有多少人真的把画图当成一个“设计问题”来对待？

大部分开发者的画图方式是这样的：接到一个任务，打开 draw.io 或者 ProcessOn，把知道的组件拖进去，连线，加几个箭头，半小时后导出一张图，贴到文档里。图看起来能看懂，但三个月后需要更新时，没人愿意去碰它——因为根本不知道怎么改，也不知道哪条线对应哪段代码。如果你也遇到过这种情况，这篇文章就是写给你的。

我的核心判断是：diagram 设计不是“画图技巧”，而是“信息结构设计”。它起码可以拆成三层来理解——语义层、结构层、视觉层，而大多数画图的人只关注了最后那一层。这篇文章会从概念讲起，对比主流工具，重点给出“图即代码”的完整工作流，再讲设计原则、协作规范、常见问题和工程建议。读完以后，你至少能把自己团队里那些“画完就废”的图，变成和代码一样能 Review、能迭代、能自动化的产物。

1. 为什么 diagram 需要被“设计”，而不是只靠“画”

先看几个真实场景。

场景一：技术方案评审。画图的人拿着自己刚画的架构图讲方案，讲了十分钟，评审的人还是没搞清楚服务之间的调用关系。不是他不认真听，而是图的信息层级太乱——网关、数据库、缓存全堆在一起，箭头上还没有标签。

场景二：项目交接。老员工离职，留下十几个 .drawio 文件。新同事打开之后发现，图里的服务名和代码里的模块对不上，有三张图内容差不多但细节冲突，最后只能重新画。

场景三：图与代码脱节。系统已经做了权限拆分，但文档里的架构图还停留在单体阶段。没人记得更新它，因为更新一次要花一两个小时，收益却不明显。

这几个场景的共同点不是“工具不好用”，而是 diagram 缺少设计过程。代码有编译期检查、有单元测试、有 Code Review，图没有。一张图一旦被画出来，就默认是“正确的”“大家都能看懂的”，这个假设在复杂项目里几乎不成立。

所以 diagram 设计到底在解决什么问题？我在工程里总结为四个维度：

• 受众问题：这张图是给谁看的？给新同学看系统全貌，给评审专家看依赖边界，给运维看部署链路，信息重点完全不同。
• 信息层级问题：什么信息需要一眼看到，什么信息是次要的，什么信息可以省略。很多图的问题不是画得太少，而是画得太多。
• 可维护性问题：图能不能在十分钟内被更新？如果一次修改需要移动二十个节点，人一定会偷懒，图一定会过时。
• 一致性成本问题：团队里 10 个人画 10 张图，风格各不相同，读图的人每次都要重新学习图例。设计规范的价值就是把认知成本收拢一次。

换句话说，diagram 设计的关键不是用什么工具，而是把图当作一种工程产物来管理。能做到这一点的最直接路径，就是“图即代码”。

2. 一张好图的底层模型：语义层、结构层、视觉层

如果不想让 diagram 变成一堆节点的随机组合，可以先建立三层思维模型。

2.1 语义层：图要传达什么事实

语义层是一张图的核心内容。比如“订单服务调用支付服务，先校验库存再扣款”，这是事实。

判断语义层好坏的标准很简单：把图里面的所有颜色、线条、装饰都去掉，只留下文字和连接关系，一个不了解项目的人能否准确说出系统在做什么。很多图的问题就是语义层混乱——一会儿画调用关系，一会儿画部署关系，一会儿又画数据流向，三种关系混在同一组节点之间，读者根本无法判断箭头到底是什么意思。

2.2 结构层：信息如何组织

结构层解决的是布局问题：哪些节点要靠近，哪些节点要分组，主方向是从上到下还是从左到右，边界在哪里。

架构图最典型的组织方式是“按系统边界分组”。订单服务、支付服务、用户服务放在同一个大框里，因为它们属于同一个业务域；数据库、缓存、消息队列放另一组，因为它们属于基础设施。用结构上的分组来表达边界，读者不用看注释也能感受到系统划分。

2.3 视觉层：颜色、形状、线条如何强化语义

视觉层是大多数人最花时间的地方，但它应该排在最后。视觉层的价值不是“让图好看”，而是“让语义更快被理解”。

一个常用的做法是建立图例：

• 颜色语义化：蓝色表示业务服务，绿色表示外部依赖，橙色表示中间件，红色表示告警路径。
• 形状语义化：矩形表示服务，圆柱表示数据库，棱形表示判断，圆角矩形表示人。
• 线条语义化：实线表示同步调用，虚线表示异步消息，粗线表示核心链路。

用一个类比来理解这三层：语义层是写文章的思路，结构层是文章大纲，视觉层是排版设计。一个高频误区是打开工具先选主题色，完全跳过语义和结构的思考。正确顺序应该是：先在脑子里或草稿纸上回答“这张图要证明什么”，再决定怎么分组、怎么排版，最后才用颜色和形状去强化重点。

3. 工具选型：图即代码，还是可视化编辑？

工具选择的本质是“维护性”与“上手成本”的权衡。下面这张表是当前比较主流的选择，注意 Mermaid 和 PlantUML 这类工具会随着版本迭代演进，具体语法以官方文档为准。