用代码画架构图：从拖拽到文本的diagram-design工程化实践

我架好一个内部项目之后，最痛苦的往往不是写代码，而是画图。给领导汇报要画架构图，给新同事讲业务流程要画时序图，给运维交接要画部署拓扑图。以前我用拖拽式工具硬画，结果每次改需求都像拆一次积木，图里线条乱得像耳机线，版本管理更是无从谈起。后来我彻底转向了“diagram-design”的工作方式——把图表当作代码一样去设计、编写、评审和维护。这篇就把我踩过的坑、总结出的流程和一套能直接上手的实操方案完整分享出来。

diagram-design，说白了就是图表设计工程化：用文本描述替代鼠标拖拽，用版本管理替代“架构图v12最终版”，用模块化思维替代一张图画到死。这套打法尤其适合开发团队、技术文档维护者、以及任何需要频繁更新图表的场景。它不只教你用什么工具，更强调的是设计图表时的思维方式——跟写代码一样，先想清楚结构，再动手落地。

我用这种模式重构了团队里一大批烂图，硬生生把每周画图的时间从三四个小时压到了二十分钟以内，而且图和代码同步更新，再也没出现过“文档里的图早过时了”这种窘境。下面我把这套方法从头到尾拆开讲。

1. 为什么我彻底放弃了拖拽式画图

先聊聊我过去画图的真实经历。以前给系统画架构图，我习惯打开一个画布类工具，从左侧拖几个方框进来，然后手动拉箭头。刚开始画还挺愉快，方框摆得整整齐齐，箭头拉得横平竖直，导出PNG发给同事，大家都说“挺好的”。但真正的噩梦发生在下一次需求变更的时候。

有一次，架构里加了两个微服务、改了一条调用链路，我打开原来的文件试图修改。屏幕上十几条连线交叉在一起，稍微挪动一个模块的位置，周边的箭头全部跟着乱掉，我重新拉了整整四十分钟，最后还是觉得箭头绕来绕去，自己看着都晕。更麻烦的是文件存在本地，换一台电脑就找不到了，同事问我“你这套架构图的源文件能不能传我一份”，我翻遍了聊天记录和网盘才找到，发给他的还是两周前的旧版本。

后来我意识到，传统拖拽式画图最大的问题不是“不好看”，而是不可持续：图的本质是信息的结构化表达，但在拖拽方式下，结构信息全部被糅在了坐标和像素里。每次修改都要跟图形布局搏斗，时间成本极高，而且没法用文本的方式对比、审阅、合并。这就像用Word画流程图，改动一次要挪半天，效率低得让人抓狂。

1.1 文本描述才是图表设计的正确输入形态

diagram-design的核心转变，是把图表从“视觉产物”变成“文本产物”。你不再关心方框该放在哪个坐标，而是描述“这个节点是什么、它跟谁有关系”。布局的脏活累活全部交给渲染引擎。我只需要维护一段结构清晰的文本，剩下的线程、对齐、分布都由工具自动完成。

打个比方：拖拽式画图就像你用手工捏陶，每次改动都要重新塑形；而diagram-design像用3D打印，你只需要修改数字模型，机器自动把实物打出来。前者费手、费眼、费时间，后者改一行代码就能重新出图。

这个思想转变带来的直接好处有三个：第一，图表进了Git仓库，每次改动都有记录，出了争议能回溯“谁在什么时候改了什么”；第二，图表可以复用，定义一次组件，多张图里引用，不用每个图里重新画一遍；第三，图表可以协同，多个同事同时修改，文本冲突可以用diff工具解决，而不是一个人霸着文件等改完再发。

1.2 不同图表工具的实际表现对比

在这一节里我对比一下主流方案。市面上的图表工具非常多，但按“diagram-design”的标准——是否可以文本化、是否易于版本管理、是否支持多人协作——基本可以分成三档。

我个人的推荐是：日常画架构图、时序图、流程图，优先选Mermaid，因为语法足够简洁，还支持嵌入Markdown文档，跟代码库的契合度最高。需要更专业的UML图，比如类图、状态图、部署图，可以选PlantUML，它对UML标准的支持更全面，生成的图形也更贴近UML规范。

我个人踩过的坑是：早期团队有人坚持用Draw.io画架构图，虽然它也能导出XML文件，但每次自动布局后XML的坐标数据都会大面积变动，代码评审里全是“删除一堆坐标、新增一堆坐标”，根本没法审。后来我们统一改用Mermaid才解决了问题。

2. 动手画图前，先想清楚四件事

很多人拿到需求就画，这是大忌。我确认要画一张图后，第一步不是打开编辑器敲语法，而是先花十分钟想清楚四个问题。这四个问题决定了图是否真的有用——技术上画得再漂亮，方向错了等于白干。

2.1 弄清楚这张图是画给谁看的

给不同的人看的图，内容详略和信息密度完全不一样。如果是画给技术团队看的，可以大胆使用专业术语、组件名称、协议细节；但如果是汇报给老板或者给跨部门同事看，那些内部服务的缩写、数据库字段级的关系就要想办法简化。

我见过一个典型翻车现场：工程师把系统的完整技术架构图直接贴进产品发布会材料，上面全是K8s、Nacos、Redis Cluster之类的术语，台下非技术观众一脸懵。后来我帮他重新画了一张简版——只有用户、前端、后端服务、数据库四个大块，用箭头标出数据流动方向，配合几句通俗说明就效果很好。

每次画图前我会问自己：如果我是第一次看到这张图的读者，我能不能在十五秒内理解这个系统的核心流转逻辑？如果不能，这个图的表达密度就有问题。

2.2 明确图表的唯一核心主题

一张图只讲一件事，这是diagram-design里最容易被忽视的原则。很多新手画架构图时恨不得把所有细节塞进去：既要画服务间调用关系，又要画数据表结构，还要标注小时延、大TPS、部署环境……最后出来的图有几十个节点，连作者本人讲起来都要找半天线从哪儿开始。

正确的做法是对复杂度做拆分。如果系统确实交互复杂，就拆成多张图，各自聚焦一个维度。画调用链路的图不铺数据库表，画数据模型的图不画网络链路。一张图讲清楚一件事，永远是黄金标准。我自己的经验是，当一张图里面的节点数量超过二十个，或者核心连线超过十五条时，就该考虑拆图了。

2.3 选对图表类型，不要乱用

图表的类型决定信息的呈现方式，选错类型再好的内容也会变灾难。下面列一下我经常用到的类型和它们的典型场景：

• 架构图：描述系统组件构成、分层结构、部署形态。
• 流程图：描述业务流程、算法步骤、异常分支处理。
• 时序图：描述多个对象/服务之间消息交互的先后顺序。
• 状态图：描述某个对象从创建到销毁经历的各种状态与事件。
• 类图：描述面向对象系统的实体结构、属性方法、继承关联关系。
• 甘特图：描述项目任务的时间排期与依赖关系。

实操中最常见的误用是把架构图画成流程图，或者把时序图硬画成流程图。前者的典型表现是：用一堆方框来表示系统各层，再用箭头描述“请求先到A再到B”，实际架构关系反而不清晰。后者的典型表现是：把“客户端发请求”“服务端处理”这种时间顺序信息强行用流程分支表达，结果分支条件根本说不清楚。

想清楚表达的是“结构”还是“顺序”，是“状态”还是“关系”，再选图形类型。

2.4 提前定好命名规范

命名是diagram-design里最不起眼但影响最深远的细节。节点ID命名混乱，会直接导致后续维护失控。我在项目里踩过的坑是：早期随手给节点起名“dsadsa”、“新建节点(3)”，到后来图一多，想找某个具体模块的图，只能一张张翻看渲染结果，完全没法从源码快速检索。

后来我定了一套规则，可以参考：一级业务模块用全称，如member-service；内部组件用模式简写加全称，如controller-auth、dal-order；外部依赖统一加前缀ext-，如ext-redis、ext-mysql-server。这套规则虽然简单，但保证了在大项目里几千个节点ID唯一且可读。

3. Mermaid 核心语法与架构图实战案例

工具选型上，我最常用的是Mermaid，语法简单、文档完善、天然适合嵌入Markdown。这一节拿一个真实案例完整走一遍，让大家看到从零到一张规范架构图的全部过程。

3.1 环境准备与三种常用启动方式

Mermaid的使用方式非常灵活，有三种方式覆盖不同场景：

方式一：在线编辑器，浏览器打开Mermaid Live Editor，左边写语法，右边实时渲染，适合快速原型验证。这个编辑器还支持把图导出为PNG、SVG，也可以直接生成指向编辑器的短链接。

方式二：本地CLI工具，通过npm全局安装@mermaid-js/mermaid-cli，命令行执行mmdc -i input.mmd -o output.svg就可以把.mmd文件渲染成图片。适合把图批量集成到构建脚本、文档流水线中。

方式三：嵌入Markdown文档，很多技术文档平台原生支持Mermaid代码块，比如GitHub、GitLab、Obsidian、Typora等。直接在文档里写入代码块，文档渲染时自动生成图形，图和文档放在同一个文件里，版本管理最方便。

我的经验：日常画图用第一种，正式交付用第二种，需要长期维护的用第三种。

3.2 手写一个标准的三层架构图

下面直接用一个电商后台的简化架构图来演示。这段代码是我从真实生产环境提取并脱敏后的版本，展示用户请求从入口到存储的完整链路。

graph TD subgraph Client[客户端层] web[Web管理端] mobile[移动端] end subgraph Gateway[接入层] nginx[Nginx网关] end subgraph Service[业务服务层] user[用户服务] order[订单服务] product[商品服务] end subgraph Support[基础组件层] redis[(Redis缓存)] mq[(RabbitMQ消息队列)] mysql[(MySQL主库)] end web --> nginx mobile --> nginx nginx --> user nginx --> order nginx --> product user --> redis order --> mq order --> mysql product --> mysql

语法本身并不复杂，里面有几个关键点值得说明一下：

• graph TD：TD是Top Down的缩写，表示从上到下布局。
• subgraph：定义子图，括号里是名称，下一行里放该组内的节点。
• 节点语法：节点ID[节点标签]，方括号表示矩形；节点ID[(文字)]，圆括号会渲染成圆柱形，适合表达数据库或缓存；节点ID{文字}，大括号表示菱形，通常用于判断节点。
• 连线语法：A --> B表示从A到B的有向箭头。

我把这段代码放进Mermaid编辑器，渲染结果就是一张层级清晰的三层架构图：客户端在最上面，中间经过网关分散到各业务服务，业务服务再访问底层的基础组件，数据流一目了然。

3.3 给架构图增加样式和主题

Mermaid默认渲染出来的图很朴素，但用它自带的主题系统也能做出很好的定制效果。我分享几个实用的样式技巧。

首先是主题选择。在编辑器或代码块参数里可以声明主题变量，常见的有default、neutral、dark、forest等。我个人习惯用neutral，色彩柔和，打印和投影都清晰。

其次是可以单独设置节点的填充色和边框。比如把不通用的故障节点标红、核心节点标蓝：

graph LR a[普通服务]:::normal b[核心服务]:::core c[故障节点]:::danger a --> b b -.-> c classDef normal fill:#f0f0f0,stroke:#666 classDef core fill:#dae8fc,stroke:#1e6bb8 classDef danger fill:#ffe6e6,stroke:#c0392b

这里用:::类名把节点关联到CSS类样式，通过classDef定义颜色、边框等具体属性。线条形态上，实线箭头-->表示正常调用，虚线箭头-.->表示异步或者弱依赖，带文字标签可以用--文字-->，实线的缩略写法---（也叫不带箭头）常用来表示无方向关联。样式技巧不需要一次全记住，用到时查CheatSheet就行，但要把“修改样式不需要重新排列布局”这个好处记在心里，这正是diagram-design带来的最大体验提升。

3.4 用状态图拆解异常流程

架构图画的是静态结构，如果要表达“某个任务从创建到失败重试再结束”的动态过程，状态图更合适。我举一个订单超时取消的简化场景，代码里每个state就是订单的一个状态，箭头表示状态迁移和触发条件。

stateDiagram-v2 [*] --> 待支付 待支付 --> 已支付: 支付成功 待支付 --> 已取消: 用户取消 待支付 --> 超时关闭: 超过15分钟未支付 已支付 --> 已发货: 商家发货 已发货 --> 已完成: 确认收货 超时关闭 --> [*] 已取消 --> [*] 已完成 --> [*]

这种图在需求评审会上特别好用，产品、开发、测试各角色都能看着状态流转来校验有没有遗漏分支。有一回我们在评审订单状态机时，当场就发现“退款中”状态在原有文档里根本没有定义，好在画了状态图，测试用例的边界条件才彻底补齐了。所以工具不是炫技，是真正帮人理清复杂逻辑。

4. 用文字设计图表时最容易踩的坑

这部分是完完全全的实战经验。Mermaid这类工具的精髓是“用文本驱动图”，但它并不是万能的，几个典型的坑我一个个说清楚，并且给出我的规避方案。

4.1 布局方向不可控：小图精美，大图凌乱

文字驱动的图表，缺点是布局算法由引擎决定，用户只能指定大方向（从上到下还是从左到右），没法手动精准锁定每个节点的坐标。图规模小的时候问题不明显，一旦节点超过四五十个，Mermaid的自动布局就可能出现交叉线，阅读起来非常吃力。

我的应对策略是强制拆图，把大图按照业务域或功能模块切成3到5张子图，然后用“总图-分图”的结构来组织：总图上只画各模块之间的核心链路，每张分图负责展开一个模块的内部细节。这本身就是diagram-design的思维——像写代码一样控制复杂度，而不是指望渲染引擎解决一切。

如果确实需要精细控制布局，比如界面原型、复杂网络拓扑图，我会转向传统画布工具。因为用了很长时间后发现，工具没有好坏，只有合适不合适。文字驱动适合逻辑、流程、关系表达，像素级设计还是交给拖拽工具更高效。

4.2 中文标签和特殊字符引发的渲染问题

踩过最坑的一次是：节点文字里写了英文会话片段，里面包含括号，Mermaid直接报语法错误。后来我才意识到，Mermaid对括号、引号、冒号这些特殊字符很敏感，需要正确转义。最稳妥的办法是给节点文本加上引号，比如：

graph LR a["会话内容: 用户(ID=001) 发起支付请求"]

这样文本里的冒号、括号就能安全渲染。如果文本特别长，还建议用双引号包裹之后再用HTML的换行标签<br/>手动分行，让方框图保持在合理宽高比，避免拉伸得不成比例。

另一个中文环境的坑是字体问题。在默认配置下渲染出的中文没问题，但如果你把SVG拿到别的软件里二次编辑，或者CI环境用Puppeteer截图渲染，有时会出现中文乱码或者字体缺字。解决办法是修改配置文件里fontFamily，显式指定系统中文字体，比如“Microsoft YaHei”或“PingFang SC”。

4.3 长文本和注释的管理

图里塞入大段说明文字是新手常犯的错误。Mermaid的图是给别人快速消费的，不是用来承载详细设计的。详细的设计说明应该写在图下方的正文里，或者用click事件把节点链接到具体的设计文档，而不是让节点文本变成一段小作文。

对于实际维护，还有一点实用技巧是善用注释。Mermaid支持%%注释行，我要强烈建议每个子图、每段复杂连线前都补上注释。这个习惯跟代码里写注释一样，时间久了自己都会感谢当时的自己：否则三个月后回来看一张几十行的图源码，根本想不起来当初为什么这么连。

4.4 版本控制与多人协同的冲突

diagram-design把图变成了文本，Git指纹天然适配了版本管理，但多人同时修改同一个.mmd文件还是可能产生冲突。尤其当两个人各自在自己分支上大幅改动同一张图时，合并起来非常痛苦。

我采取的是“图源文件模块化”的方式：把公共的节点定义拆到单独的文件里，比如common-nodes.mmd，不同业务图各自画各自的连接线，用Mermaid的!include指令（配合社区的一些扩展方案）复用公共节点。虽然Mermaid原生的include支持在不同环境中略有差异，但思路本质上是“把公共依赖抽成共享模块”。如果项目用的是GitLab或GitHub这类平台，也可以考虑给.mmd文件配上CI流水线脚本，当代码合并后自动渲染出最新的图并发布，这样团队成员在空闲时间查看在线版的图就够了，不用每个人都跑一遍本地渲染。

5. 从图表设计到图表体系：协作流程与长期维护

单张图画得好不算本事，能维护一整套长期存活的图表体系才是真正受益的地方。这一节说的是我把diagram-design落地到团队协作后的实践沉淀。

5.1 图表代码纳入评审流程

在团队里，我把图表源文件纳入代码评审范围，效果立竿见影。以前图是“画完就发”，现在图是“提交就审”，任何架构调整都先过评审再合入。有一次评审中，同事发现一张图里订单服务的调用箭头画反了，如果没有人仔细看这张图，这个误导信息就会一直留在文档里影响后面维护的人。

实操上没什么特殊工具，就是把.mmd文件当成普通源代码，提交到同一个仓库，pr描述里附加渲染出来的图片预览。评审人通过查看渲染预览提出修改意见，提交人修改后重新渲染，整个流程完全符合代码评审习惯。

5.2 图表即文档：图与文字的互补

我推崇的是“图即文档，文字作补充”。在技术方案设计文档里，先画核心架构图，再配上一段文字描述关键决策。图给出全景视图，文字解释为什么这样做，两者各司其职，不重复不替代。

具体做法是：架构决策记录里维护一个图表目录页，每张图都配上唯一编号和简短说明。新同学入职看这个目录，半小时就能对系统有个全景认知，比翻几个月的文档高效得多。在后来的实践中这个目录页还承担了新人培训材料的功能，他们看完图再直奔代码，上手的节奏快了很多。

5.3 用模板沉淀经验，让团队画图水平整体提升

最后分享一个团队规范方面的做法：我建了一个图表模板库，把常用的架构图模板、时序图模板、状态图模板全部沉淀成公共文件，团队成员画新图时基于这些模板起步，而不是从空白文件开始。模板里已经预置了命名规范、层级划分、常用颜色语义，新图的风格自然统一，后续合并和维护都省心。

光有模板还不够，还要有“为什么这样画”的说明。我在每个模板文件头部用注释写清“这张图表达了什么场景”“哪些节点必须画”“哪些细节不要画”，相当于把设计原则固化成了可执行的规范。这样一来，团队里每个人画出来的图都有一定的下限，不会出现风格差异巨大的“百图百样”。

6. 从单张图到图表体系：我最后的几点实操心得

当图表形成了体系，真正的红利才会体现。我自己在跑了小半年这套流程之后，明显的体感变化是：画图不再是一种负担，而是一种思考工具。遇到模糊不清的业务流程，随手起一个临时图文件，用几分钟勾勒出各方关系，想不清楚的地方立刻暴露出来。这在过去是不敢想象的，以前画一张图成本太高，宁可先想“明白”再画，但很多问题恰恰是画的过程中才能想明白。

这里分享三个具体心得，都是常规文档里不会写的内容。

第一，尽量让箭头方向跟阅读方向一致。如果总方向是从上到下，那么所有返回性的箭头（比如响应、回调）也尽量画成从左到右，而不是原路折返，认准核心链路，用主方向表达主要数据流。这一点在文字驱动引擎里没法直接指定，但通过合理拆分上下层级，能减少大量交叉线。

第二，命名规则一旦定下来，就不要轻易改。有一次我为了“简洁好看”，把节点ID从带业务的命名改成了缩写，结果半个月后重看图源码，差点认不出每个节点是什么。命名是图表的寻址系统，它不稳定，整张图的长期价值都会大打折扣。

第三，如果想要导出更高质量的图片用于排版印刷，请务必渲染成SVG而不是PNG。SVG是矢量格式，任意缩放不模糊，而且可以用文本编辑器直接打开修改，内部结构都保留了索引信息，后期替换文本或改色非常方便。

最后，我还想补充一个很多教程忽略的点：图表设计本质上是一种沟通技术。工具、语法、布局都是为了降低沟通成本。对开发团队来说，好图减少重复提问、加快新人上手、让架构评审更聚焦；对跨团队协作来说，好图能避免几十轮无休止的解释会议。如果把“画图”当作“用代码编排信息”，那么diagram-design带来的不只是效率提升，更是一种更透明、更高质量的协作方式。强烈建议每一个经常画图的人试一试这套流程，特别是那些还在被拖拽式画图折磨的同行，转过来之后你就不会再想回去了。