代码化图表设计：让架构图、流程图和ER图成为可维护的代码-北京尧图网络

今天想认真聊聊 diagram-design 这个技术实践。简单说它属于“用代码来画架构图、流程图、这些日常要用的图”这一大类需求。说得白话一点就是把以前在画布上拖拽方框、连线的方式换成写文本、跑命令、出图的方式让整套流程图设计变成可版本管理、可评审、可自动生成的内容。这篇文章适合每天要和系统架构图、时序图、ER图打交道的开发、运维和文档工程师也适合团队里负责技术方案评审、外包交付说明的朋友。我会从为什么值得做、工具怎么选、实际怎么操作、踩过哪些坑这几个角度把自己这几年的真实经验拿出来讲透。1. 先聊清楚代码化图表设计到底解决了什么问题1.1 从“画完就过期”到“图表即代码”以前在图形界面里画架构图流程大概是新建画布拖一个框写着「Nginx」拖一个框写着「后端服务」连线标注端口号导出图片贴进文档完了。这套流程最大的问题是“维护”。线上架构改了一次负载均衡多了一层数据库读写分离了文档里的图还是三个月前那张。因为改图成本高——打开文件、找图层、调整连线、重新导出——人一旦懒下来图就和现实脱节了。我后来彻底换了个路子所有图都用文本描述交给渲染引擎出图源文件进代码仓库。架构变了就改几行文本提交一个 commit图自然就跟着变。这背后其实就是“图表即代码”的思路图不再是某个图形文件而是一段文本文本可以用 diff 对比可以走 code review可以在 CI 里做语法校验。用一个生活化的类比。以前画图相当于手写笔记写错了要涂改重写整页改多了笔记一团乱。代码化图表相当于在电脑上打 Markdown改一个字是一瞬间的事历史版本都在谁改了什么看得一清二楚。对于团队协作来说这个差别是天壤之别。1.2 什么场景真的值得用什么场景千万别用不是说所有图都应该代码化。我自己的判断标准就一条这张图需不需要持续维护如果它是一次性输出比如给汇报 PPT 画一张概念图那用图形工具拖一拖调调颜色三分钟搞定没必要写代码。需要长期维护、多人协作、频繁变更的图代码化就非常香。系统部署架构图是最典型的例子。我们团队有一个几十个节点的微服务架构图工具里拖拽编辑一次要一个上午改成分段描述之后加一个服务只需要加三行删一个服务只需要删三行。加上代码评审流程架构调整被卡在评审阶段就发现根本不会出现“图早就跟不上了”的情况。下面是几个典型的适用场景系统架构图部署拓扑、服务调用关系、网络分区关系时序图/流程图业务流程、接口调用链、状态机流转ER图数据库表关系尤其是需要跟表结构定期同步的场景C4 model 架构描述用代码维护多级别的架构视图从系统上下文到类级别不适合的场景也很明显你觉得图形引擎的默认布局不能满足你的审美你必须精确控制每个节点的像素位置那代码化路线会让你非常痛苦做数据可视化的复杂图表比如热力图、桑基图需要处理大量真实数据应该直接用专业可视化库还有画营销海报这样的创意设计那是设计工具的范畴跟 diagram-design 半毛钱关系都没有。2. 工具选型主流图表方案横向对比与取舍2.1 Mermaid易写、生态好、内存友好Mermaid 是目前最流行的代码画图工具它的语法非常接近 Markdown学习成本几乎为零。不需要安装软件在浏览器里就能跑官方 live editor渲染一块图就是敲几行文本的事。GitHub 的 Markdown 原生支持 Mermaid 代码块这给技术文档带来了很大的便利。它支持的图类型也很全面流程图、时序图、类图、状态图、甘特图、ER图、需求图、饼图、思维导图。我最常画的是部署架构图和状态流转图子图语法可以快速把「网关层」「服务层」「存储层」这些区域拢在一起。Mermaid 的劣势在于对复杂图的布局控制力较弱。图一复杂节点一多默认布局可能产生很多交叉线它不支持手动锁定节点坐标。所以我的经验是Mermaid 适合中型复杂度、强调快速迭代和文档内嵌的场景。2.2 PlantUML序列图老牌劲旅PlantUML 也是基于文本的绘图工具跟 Mermaid 是竞品的关系。它的强项是时序图和 UML 全套图。我的感觉是如果你所在的团队之前用的是 UML 方法论那 PlantUML 的语法风格会让你更有亲切感。它支持 skinparam 和 theme 做全局主题定制对细节样式控制比 Mermaid 强一些。PlantUML 用起来有两个小门槛一是需要 Java 环境初次环境配置比 Mermaid 慢二是在中文字体渲染、导出图片样式上偶尔会遇到字体问题需要额外指定 font。不过这些年用下来稳定性其实很好。坦率说如果今天从零开始选型Mermaid 会因为生态和易用性占一些优势但 PlantUML 在 UML 图和复杂序列图这个专项领域仍然值得驻足。2.3 Graphviz老而弥坚的“骨架”引擎Graphviz 严格来说不是画图工具而是一个“布局引擎”它接受 DOT 语言描述的图结构然后通过算法自动计算节点坐标。它擅长渲染有向图、无向图核心优势是布局算法的成熟度。复杂的依赖关系图用 Graphviz 处理出来的效果往往比 Mermaid 更好。但 Graphviz 有个学习曲线DOT 语言语法跟 Mermaid 不是一个路子刚上手会觉得别扭。而且 Graphviz 的节点样式比较朴素四周的边距、字体默认值都需要调。它更像一个底层引擎适合做自动化批处理比如从代码扫描依赖关系批量生成模块依赖图。给一个简单的 DOT 示例digraph G { rankdirLR; A - {B, C}; B - D; C - D; D - E; }这段描述的是 A 触达 B 和 CB、C 都指向 DD 再指向 E。引擎会自动排列节点位置减少交叉。这个“由引擎自动排布”的思路也是 diagram-design 这个方向很重要的一个根基——图的质量不应该靠手调而应该靠算法保证基本盘。2.4 draw.io / Excalidraw 等图形化工具的补充定位我并不是说图形化工具不能用了。恰恰相反draw.io 和 Excalidraw 这类工具应该留存在你的工作流里只是定位不同它们是思考工具不是交付工具。做架构方案的时候一开始脑子里的结构是模糊的,在白板上随手画一画比敲代码快得多。这个阶段是“从混沌到条理”用 Excalidraw 的手绘风白板流程可以让思路快速成形。真正把方案确定了、要固化到文档里的时候再用 Mermaid 或者 PlantUML 敲一份正式交付图。四类工具的定位微妙不同我做了个速查表工具核心强项适用场景我的主观评分5分制Mermaid易学、生态好、原生支持广文档内嵌、快速制图4.5PlantUMLUML规范完整、序列图专业规范UML图、复杂时序4.0Graphviz布局算法强、适合自动化依赖图、批量生成4.0draw.io / Excalidraw自由排版、视觉可控头脑风暴、一次性示意图4.0定位不同选工具别上来就抠功能先看你最常画的是哪种图再决定主工具常画架构图和状态图选 Mermaid常画时序图和类图选 PlantUML要做自动化批量出图Graphviz。3. 实操用 Mermaid 从零搭建一张部署架构图3.1 核心语法快速入门Mermaid 的流程图语法是学习成本最低的。用flowchart LR或者graph LR声明方向从左到右TB声明从上到下。节点和连线的写法很直观我用一张实际部署架构图来演示。下面这段描述一个典型的 Web 前后端架构包含负载均衡、前端、后端、数据库、缓存flowchart LR subgraph Edge[边缘接入层] LB[负载均衡] end subgraph App[应用层] FE[前端应用] BE[后端服务] end subgraph Data[数据层] DB[(MySQL)] RC[(Redis)] end User[用户] -- LB LB -- FE LB -- BE FE -- BE BE -- DB BE -- RC这里几个语法点值得强调节点后面跟方括号[文本]表示矩形节点跟圆括号(文本)表示圆角矩形跟花括号{文本}表示菱形判断节点跟双括号[(文本)]表示圆柱体也就是数据库。--是实线箭头---是普通实线-.-是虚线箭头是粗实线箭头。subgraph可以把一组节点聚合成一个区域块在架构图里就是分层的核心手段。看这张图就能明白用户经过负载均衡分流到前端和后端再分别访问数据库和缓存。整张图只有几十行文本但表达的信息密度远超手画图。再给一个带条件分支的流程图例子flowchart TD A[收到请求] -- B{是否登录} B -- 是 -- C[执行业务逻辑] B -- 否 -- D[跳转登录页] C -- E[返回数据]这里的B{是否登录}是判断节点连线上可以加文字标签用-- 文本 --或|文本|都可以。3.2 连线方向和子图划分里的门道很多人照着 Mermaid 文档写的图不难看但一复杂就乱。问题往往出在连线的方向定义上。Mermaid 有两种声明方式graph TD代表从上到下graph LR代表从左到右在复杂图里混用方向很容易打造灾难布局。我自己的经验是框定整体方向后子图内部的方向尽量跟全局保持一致。比如一张系统架构图全局我用LR让用户流从左到右推进子图内部如果节点关系是层级调用可以单独用TB组织但不要让一条长连接横穿多个 subgraph这会直接导致边缘交叉混乱。另外要给子图起有意义的名字。subgraph App[应用层]里的App是节点表中的标识符[应用层]是渲染出来显示的文字。如果不写方括号文本图上就会显示英文标识符中文环境下观感差很多。对节点数量的控制我的经验是一张流程图里的节点控制在 10-15 个以内。超过这个数字布局算法的交叉率会急剧上升。如果架构里的节点真的很多应该按层或按模块拆成多张图用「总图 — 分图」的方式组织而不是硬塞进一张。3.3 样式定制把重点节点“标”出来默认渲染的图形颜色比较素所有节点都是一个色。我可以接收但在技术评审时大家更愿意看到重点分层的节点有个颜色区别。Mermaid 提供了classDef语法用于给节点定义样式flowchart LR classDef gateway fill:#f9f,stroke:#333,stroke-width:2px classDef service fill:#bbf,color:#fff classDef storage fill:#bfb LB[负载均衡]:::gateway BE[后端服务]:::service DB[(MySQL)]:::storage:::gateway这种写法把节点归入 gateways 类classDef gateway fill:#f9f定义了填充色。实际操作里我会统一三类颜色网关层用浅紫底色服务层用浅蓝存储层用浅绿。颜色不是装饰是为了让看图的人一眼建立「层」的认知。除了颜色还有两个实用技巧点击跳转在 Mermaid 节点上可以挂点击事件把节点链接到对应服务的文档页。语法是click BE https://example.com/docs/backend。在演示环境里别人点一下架构图的节点就能直接进到服务说明体验远超静态图。备注节点上可以加classDef之外的备注连线上建议只标注必要信息端口号、协议、数据量不要什么信息都塞在线旁边。4. 进阶玩法把图表做成团队的“活文档”4.1 文档内嵌与渲染链路代码化图表最舒服的落地场景就是嵌入文档。在 GitHub 上写 Markdown 文档直接放一个 mermaid 代码块页面会自动渲染。不需要配套任何工具链也不需要安装插件。但本地工作流里我们经常需要生成图片文件用于技术评审附件、外包交付说明和演示 PPT。这时候需要一个渲染命令行工具我们会用 Mermaid CLI它可以把一个.mmd文件导出成 PNG 或 SVGmmdc -i architecture.mmd -o architecture.png -w 1600 -b white参数-i指定输入文件-o指定输出文件-w设置图片宽度-b设置背景色。导出时建议主题统一我们通常在.mmdc.json里配置默认主题和字体{ theme: neutral, fontFamily: PingFang SC, Microsoft YaHei, sans-serif }导出 PNG 有个坑中文字体渲染。如果你的命令行环境里没安装中文字体渲染出来的图就是方块。解决方法是让系统装上字体或者在配置里指定字体族。4.2 CI 里做图表语法校验杜绝“破图”入库团队协作里经常出现一种尴尬代码评审的时候有人改了一个 mermaid 文本缩进错了一位或者引号不匹配图表直接渲染失败整个页面碎掉一块。这种问题靠人眼很难及时发现因为评审人往往注意看文字内容不太注意图形是否正常。解决思路是把图表校验放进 CI。我们用的 GitLab CI 和 GitHub Actions 里都有一条流水线专门跑 Mermaid CLI 的-c模式或者用专门的 Mermaid lint 工具来校验所有.mmd文件和 Markdown 里的 mermaid 代码块。语法有问题构建直接标红开发者必须修复之后才能合并。这个做法带来的收益是架构图和代码是同一套质量门槛。「坏图」没办法进入主干整个文档体系的可信度就会高很多。4.3 从数据库 Schema 反向生成 ER 图数据库表关系图是「活文档」需求的另一个高发区。表结构一变图很容易没跟上。代码化思路在这里同样能发挥作用基于数据库连接信息反推表结构自动生成 mermaid 的 erDiagram 代码。例如用某个数据库工具直接分析连接串就能生成erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ ORDER_ITEM : contains ORDER_ITEM }|--|| PRODUCT : ordered这种动态生成的 ER 图最大的价值在于“不会过期”——表结构调整之后重新跑一次生成脚本图就同步更新了。把生成过程放在 CI 里每次表结构变更合并时自动刷新文档业务方和开发方永远看到同一份模型定义。4.4 技术评审和演示中的“讲图”能力工具和语法都只是基础真正加分的是“讲图”能力。我见过不少团队代码化图表玩得很溜但评审的时候只是把图贴出来没人讲解。图是静态的但图的阅读路径和关键节点需要有意识地设计。我的习惯是每张架构图配一小段说明文字讲清楚“主路径”是哪条“链路”。比如用户请求经过网关流转到服务层的路径用文字一行行带出来。在评审时按照代码图里从入口到出口的顺序讲而不是随机跳跃。这张图的“变化点”要有颜色标识。新加的服务标红删除的组件用灰色虚线表示评审人打开图就能锁定改动区域。这样图就不再是文档里的一件装饰品而是评审讨论的主线。5. 常见问题与踩坑实录5.1 图太大渲染出来严重挤压走形Mermaid 渲染大量节点的时候默认布局会出现节点交叉、过长边、无法直视的情况。这是我们最常遇到的坑。首先是布局方向。流程图从LR改到TB可能产生完全不同的效果。图偏宽就换TB偏长就换LR优先保证长边在横向或纵向都顺眼。然后是合并同类节点。多个业务模块共用同一个依赖可以把它们放进一个 subgraph减少全局里的“飞线”。再者使用direction TB或direction LR指令在子图内部指定方向甚至可以部分缓解布局混乱。如果图节点实在太多拆图是唯一最优解。架构总图只放分层和关键链路每一层的细节单独出一张图。这样既能保持阅读体验也能让每张图在后续维护中保持可管理的大小。5.2 中文乱码和字体设置问题中文字体问题在导出 PNG 和 SVG 时出现得最多。在浏览器里渲染基本不需要处理字体问题但命令行导出会遇到系统缺字体的情况。我的处理方案很朴素在渲染环境的系统里装好「Noto Sans CJK」或「思源黑体」并在 Mermaid 配置里指定所用字体。然后导出的前两步先出一张测试图确认中文没有变方块再批量渲染。另一个跟字体相关的细节是SVG 里的文字路径在某些阅读器里会偏移看起来像错位。遇到这种情况宁可直接导出 PNG省心。我在某些文档工具里踩过 SVG 字体路径不一致的坑后面统一切到了高分辨率 PNG问题直接消失。5.3 不同平台对 Mermaid 版本支持不一致GitHub、GitLab、语雀、Notion这些平台对 Mermaid 的支持程度并不一致。GitHub 文档仓库渲染用的版本可能持续更新但企业内部的 GitLab 用的还是老版本。同一个语法在不同版本上的表现差距不小。一个最典型的情况是我在新版 Mermaid 里用了箭头样式--o和--x渲染没问题提交到公司的 GitLab 里直接语法报错。这种事确实烦人所以在多人协作里先确认目标平台的渲染版本不留暧昧区间。我的标准操作是先用本地 CLI 渲染出图片确认语法正确再把文本提交。如果目标平台必须用自身渲染那就用一种最小化冗余的语法风格不用新特性不用花哨写法保证兼容性。5.4 团队文档很难保证所有人都更新图最后这个坑不是技术问题是沟通和管理问题。有些人改了代码图没改有些人改了图图里的服务名跟代码不一致。我试过的应对方案里最有效的是把「更新架构图」加入代码合并的 checklist。在团队代码仓库的合并请求模板里加一项「本次改动是否影响架构图影响则同步更新」。友好一点的做法是在架构图文件头部加一段注释写明「此图由代码生成源文件见 docs/architecture.mmd禁止手动编辑图片」。再加上 CI 校验保证图文件永远跟着代码一起变化。这套组合拳下来图滞后于代码的情况基本绝迹。6. 个人经验与建议回看这几年的实践我对 diagram-design 的体会是它的价值核心不是“用代码代替鼠标”而是让图变成可以被维护、被审查、被版本管理的一等公民。我见过太多同事从“画图两小时、改图两小时”的痛苦里解脱出来也见过团队因为图滞后导致评审会变纠错会。我的建议是切入路线要低门槛从一次你要做的架构调整开始别着急把所有旧图都翻新一遍先在新增的架构迭代里用 Mermaid 出图画完顺手放进文档仓库等习惯了这种工作流再把存量图逐个迁移。这样既不会颠覆现有流程又能尽快体验到“改一行文本、提交一张图”的快感。还有一个值得坚持的好习惯每次做完方案把图和背后的决策理由一起留到文档里。为什么这里用队列解耦为什么那里要拆服务在图的某个注释里写清楚。图解决“是什么”注释解决“为什么”这两样东西合在一起才是团队真正需要传承的知识资产。

代码化图表设计：让架构图、流程图和ER图成为可维护的代码

相关推荐

Claude + IDEA + CC-GUI：Java开发的最佳AI组合神装！TaoToken统一Key接入实战

AI赋能计算力学：从物理信息神经网络到代理模型的落地路线

LangGraph实战：用图结构编排Agent工作流，突破复杂业务状态管理瓶颈

更多资讯

顺序表逆置：双指针原地算法原理与工程实现

AI报销实践：从1小时到5分钟的流程改造与落地指南

Ionic 表单与输入框实战指南：从基础到进阶

戴尔集成阵列S150驱动详解：从Windows到ESXi部署与排错

SAP MTO成本核算全解析：销售订单控制与生产订单结算配置指南

CVI计算器完整工程实战：从回调绑定到异常处理

今日更新

NetSpot 实战：用信道分析与频宽优化解决 Wi-Fi 卡顿

C++ split() 字符串分割的五种实现与性能实测

R语言坐标轴范围设置：从xlim/ylim到coord_cartesian的完整指南

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？