如果你和我一样接过不少前后端、数据平台的设计任务一定对“diagram-design”这个标题不陌生。它不是某个炫酷的新框架也不是花哨的可视化工具集而是一整套把“画图”变成软件工程流程的思维和配套实践。说白了就是用代码来画架构图、流程图、时序图和部署图让图形像源代码一样被管理、评审、审计和复用。我最初接触这个思路是在一次系统重构的启动会上当时团队要在一周内完成对旧系统全链路的梳理靠白板和截图根本维护不了三四十张图。后来我们把 diagram-design 纳入了日常研发流程所有图表进入仓库、走评审、参与自动化检查才终于把“图上画的和代码里写的”对上了。这篇文章就围绕我在真实项目里沉淀下来的这套工作流展开适合正在做微服务拆分、系统技术改造、平台能力建设或文档体系升级的工程师也适合刚接手复杂项目、需要快速读图维护图的同学。我会把选型、环境、语法细节、设计规范、CI 集成和踩坑实录都摊开讲。1. 项目背景与现实痛点1.1 为什么单独把“图表设计”当工程来做很多开发团队把画图当成写文档的附属品需求评审时白板随手一画拍个照丢进 wiki 就算完事。这种方式在项目早期问题不大可一旦系统进入稳定迭代期图件就会成为“最熟悉的陌生文档”上线半年后没人敢动那张图因为不确定它和当前代码是否一致新人入职后照着过时的架构图去排查线上问题绕了整整一天弯路。我开始把 diagram-design 当作独立工程任务来处理起因就是一次事故复盘。某团队处理一个支付回调链路的设计图图上画着三个服务但实际代码已经拆分成了五个。新来的同事按图索骥把问题定位到了已经废弃的模块上结果耽误了变更窗口。复盘结论里只有一句话图和代码的同步机制缺失。这句话背后需要的不是多画几张图而是完整的图设计工作流——从选型到存储、从可视化到校验、从评审到发布每一步都要有规矩。1.2 设计目标是可维护、可评审、可追溯diagram-design 和普通“画图”最大的不同在于三个可可维护、可评审、可追溯。可维护指的是图件不是一张静态 PNG而是一个可以 diff 的文本源文件。任何人改了代码都能顺藤摸瓜找到对应图件花两分钟改掉再提交、再评审。可评审指的是图件能像 PR 一样被团队成员逐行 review。白板上的图只能以“印象”评审文本化的图则能以“逻辑”评审。评审人能把注意力放在模块边界、依赖朝向和数据流是否合理上而不是花力气重新描一遍线条。可追溯则要落到版本管理上。每次迭代都对应一个图版本线上出问题的时刻对应哪个版本的部署图打开历史记录一目了然。团队里曾经为了确定某个缓存组件是哪次重构引入的翻了半天的聊天记录。现在只需要看一眼文件提交历史变更原因、提交人、关联需求全部对上。这三种能力是手画图形阶段无论如何都给不出的。2. 技术选型与对比取舍2.1 文本化图表方案横向对比做 diagram-design 的第一步是选一个“能用代码描述图形”的工具。市面上的方案很多我实际用过的有三种Mermaid、PlantUML 和 Graphviz。它们都能把文本定义解析成图表但侧重点完全不同。Mermaid 的语法最接近自然语言flowchart、sequenceDiagram 写起来像在描述一个过程。比如画一个下单流程几乎不需要记忆复杂关键字缩进和箭头符号就能表达意图。PlantUML 是传统 UML 建模的老牌方案类图、用例图、状态图的标准语法非常完整在软件建模场景下几乎没有短板但学习曲线比 Mermaid 陡。Graphviz 则更偏底层它用 DOT 语言描述图结构布局算法非常强大特别适合节点多、边关系复杂的拓扑图不过装饰性和可读性需要自己调。三者不是替代关系。我的经验是流程和时序图用 Mermaid因为写起来快读起来顺正式的 UML 类图、部署图和用例图用 PlantUML因为建模语义更专业涉及几十个节点、有复杂依赖关系的系统架构总览用 Graphviz因为布局自动化的效果最好。这个组合基本覆盖了日常开发中 90% 的图形需求。2.2 为什么优先选择 Mermaid 作为主力工具如果只能在团队里推一种方案我会选 Mermaid。核心原因是它在“开发效率”和“上手成本”之间的平衡做得最好。Mermaid 的语法设计理念是“所见即所得”你写出来的几乎就是你想讲的逻辑。画一个用户登录的时序图只需要列出参与者、箭头和说明文字渲染出的图即使不做样式调优也能准确传达语义。这一点对团队协作非常重要——不是每个人都是专业架构师也不是每个人都愿意为了画一张图去学一门新语言。Mermaid 本身是一个 JavaScript 渲染库所以它能非常自然地嵌入到 Markdown 文档、静态站点甚至前端页面中。很多团队把架构说明直接写在 README 里Mermaid 代码块被渲染成图形源码和图形放在同一份文档里天然解决了“图找不到”的问题。另外 Mermaid 官方在持续维护新版本对各类图表的支持越来越完善GitHub 和多数代码托管平台也都原生支持 Mermaid 渲染。对于一个长期演进的项目来说选择活跃维护的工具等于给图资产上了一道保险。2.3 PlantUML 与 Graphviz 的适用边界PlantUML 我一般在处理“严谨建模”时才会动用。比如要画一个支付领域模型的状态图需要清晰表达“待支付—支付中—已支付—已退款”之间的转移条件和动作PlantUML 的 state diagram 表达能力远强于 Mermaid。它的语法围绕着 UML 规范组织市面上学 UML 的书籍、资料基本可以直接迁移。另一个典型场景是类图设计。做领域驱动设计时我需要把聚合根、实体、值对象、领域服务之间的关系画清楚PlantUML 的类图支持继承、组合、聚合、依赖等多重关系渲染结果接近教科书插图评审会上信息损耗极小。Graphviz 则用于“自动布局优先”的场景。当系统包含超过三十个业务模块服务间依赖关系多到手工调整位置会疯掉时Graphviz 的 dot 布局算法会根据边的关系自动安排节点位置倾向减少交叉。虽然渲染出的图离“美观”有距离但在表达依赖结构方面准确性很高。我通常用它生成数据血缘图、部署拓扑图、第三方依赖关系图这些图没人指望“好看”但必须“不出错”。3. 环境准备与项目初始化3.1 工作区规划与依赖安装在动手写第一张图之前我建议先把工作区规划好否则图多了之后会很痛苦。我的做法是在项目根目录下建立一个 diagrams 目录内部再按业务域分子目录diagrams/ ├── docs/ # 全局说明文档、评审记录 ├── flows/ # 业务流程图、状态流转图 ├── system/ # 系统架构图、部署图 ├── sequence/ # 时序图、调用链图 ├── uml/ # 类图、用例图 └── assets/ # 自定义样式、脚本这样划分的好处是某人想找“订单流程”的图直接进 flows 目录检索想确认最近部署架构的变迁看 system 目录的提交记录。目录命名尽量用英文小写加横线保持跨平台兼容。依赖安装方面纯本地开发我可以只用 Mermaid CLImermaid-cli来做渲染配合 VS Code 的 Markdown Preview Mermaid Support 插件实现实时预览。渲染命令建议固定一个版本写入 package.jsonnpm install -D mermaid-js/mermaid-cli npx mmdc -i flows/order-flow.md -o docs/order-flow.svg如果团队里有人习惯用 Python 工作流可以用pip install plantuml配合本地 jar 包执行 PlantUML 渲染。Graphviz 的安装同样简单macOS 下brew install graphvizUbuntu 下apt-get install graphviz即可。3.2 Git 仓库初始化与目录规范图文件的版本管理是整个体系最容易被忽视、又最重要的一步。我建议在仓库根目录建一个.gitattributes文件固定图件文本和渲染产物的处理方式*.svg binary *.png binary diagrams/** text eollf.gitattributes的作用很直接保证跨平台时换行符一致避免别人一拉代码图文件整体 diff 成乱码。对于渲染生成的 SVG 和 PNG不建议放到源码仓库里更合理的做法是加入.gitignore让 CI 在构建时统一生成并发布到文档站点。diagrams/.render/ diagrams/**/*.svg diagrams/**/*.png实际协作里文本源文件才是真正需要评审和追溯的资产。渲染产物属于“生成物”任何人都不应该手工编辑否则下一次 CI 覆盖时就会产生无谓的冲突。把“源文件入库、渲染产物出仓”的边界划清楚是图资产工程化的起点。4. Mermaid 图表设计实操手册4.1 基础语法与第一张流程图熟悉 Mermaid 最简单的路径是从 flowchart 开始。你不需要懂任何编程概念只需要理解“节点”和“边”。节点就是方框里的文字边就是箭头。举个例子画一个“用户下单”的流程flowchart LR A[用户下单] -- B{库存检查} B -- 有库存 -- C[扣减库存] B -- 无库存 -- D[提示缺货] C -- E[生成订单] D -- F[结束] E -- G[返回支付页面]这里LR表示从左向右布局A、B是节点的 ID方括号表示普通矩形节点花括号表示菱形判断节点。箭头--上可以挂文字比如-- 有库存 --。整个过程对应着代码里的一个决策分支图面向产品也好、面向开发也好都清晰直观。初学者最常见的错误是把节点 ID 写成中文这在一些渲染环境里会触发编码异常。我的建议是ID 一律用英文驼峰或下划线命名中文只出现在显示文本里也就是方括号内的部分。比如A[用户下单]ID 是 A中文是展示内容稳得很。4.2 时序图与状态图的写法要点时序图是表达跨服务调用的利器。Mermaid 的 sequence 语法把参与者定义为participant然后用箭头表示消息传递sequenceDiagram participant U as 用户端 participant S as 订单服务 participant P as 支付服务 U-S: 提交订单 S-P: 创建支付单 P--S: 支付预处理结果 S--U: 返回支付链接 U-P: 完成支付 P-S: 发送支付成功回调-表示同步请求--表示异步返回activate和deactivate可以控制激活框。写时序图时最容易忽略的是“失败分支”。真实分布式系统里支付服务不是一定返回成功超时、重试、补偿回调都是常态但这些逻辑在实际图里往往被省去。后来我们团队立了规矩每张时序图必须画出至少一个异常路径哪怕只在边旁标注“失败”图才有参考价值。状态图则适合描述对象的生命周期。Mermaid 的 stateDiagram-v2 语法可以定义状态、转移条件和内部动作。写状态图重点别放在“有多少个状态”而是放在“状态如何被别人改变”。比如一个订单有“待支付”“已支付”“已关闭”驱动它变化的可能是用户、可能是超时任务、也可能是支付回调。把转移事件写清楚图才能指导开发编写状态机代码。4.3 子图与样式控制让图分层不糊成一团系统架构图一旦超过三十个节点平面布局就会暴露出“协调性”问题。Mermaid 的 subgraph 可以给节点分组用容器表达模块边界让图整体有层次感flowchart TB subgraph 接入层 G[网关] end subgraph 业务层 A[订单中心] B[支付中心] end subgraph 数据层 D[(订单库)] E[(支付库)] end G -- A G -- B A -- D B -- E样式控制上Mermaid 支持在 script 区用 CSS 风格覆盖节点颜色、边框和连线粗细。比如当某个服务处于重构期需要高亮可以在图末尾加上style B fill:#f9f3cb,stroke:#caa53d,stroke-width:2px高亮不只是为了“好看”更是为了在评审会上直接表达“范围”。一张只有黑白线条的架构图里投入人眼去分辨变动模块太费劲用颜色把本次要改、下周要动、完全不碰的模块分开讨论效率能提升一个档次。4.4 长图拆分的段位技巧我见过不少架构图长度超过一个屏幕滚动起来像卷轴。这种图们虽然覆盖了所有细节但实际上没有人会认真读完。更好的策略是“一图一主题”把长图拆成多张彼此有引用关系的短图并通过共用节点 ID 衔接。举例来说一个完整下单链路图可以拆成“用户侧交互图”“服务端处理图”“数据落库图”三张每张图只讲一个阶段。用户侧图结束时指向“订单服务”服务端处理图从“订单服务”开始节点 ID 保持一致图形上看着不连续但读者跳转是顺畅的。这里的关键是在文档里写明图与图之间的联系和入口例如在每张图下方标注“继续看下一阶段见 x 文档”。经验是一张图超过 50 个节点阅读成本就已大于收益不如拆分。5. 设计方法论与规范沉淀5.1 抽象分层从需求图到设计图到部署图diagram-design 最容易犯的毛病是把所有信息塞进一张图里。我在评审中反复强调的一点是必须分阶段出图。业务需求阶段画“需求图”描述用户角色、业务流程和关键规则这时的读者是产品和业务方系统设计阶段画“设计图”描述模块划分、接口通信、数据存储和依赖关系这时的读者是研发上线运维阶段画“部署图”描述实例拓扑、网关路由、中间件集群和容灾边界这时的读者是运维和值班同学。同一件事在不同图的视角里表达完全不一样。拿支付来说需求图画的是“用户选支付方式—确认—扣款—显示结果”设计图画的是“支付网关—支付渠道—回调通知—订单状态更新”部署图画的是“支付服务两个实例—Redis Cluster—MySQL主从—消息队列”。三层图里要用同一套核心名词比如“支付单号”“回调地址”否则读者容易晕。实践证明分层出图能避免一个重要问题评审组在需求阶段就开始争论部署架构谁也说服不了谁。5.2 命名、色彩与注释规范图件长年演进之后最大的隐患是图例不统一。不同作者风格不同节点命名方式千奇百怪。我在项目启动时就定了一套团队内部规范效果很好。命名上所有服务节点统一用“域模块动词/名词功能”的格式比如“订单服务”“库存服务”禁止直接写 IP 或模糊缩写。注释上关键分支必须写明判断条件比如“库存检查里 缓存缺失 则走查库”。色彩上绿色代表稳定模块红色代表本次改动模块灰色代表即将下线模块这种约定俗成能让人眼聚焦。我还要求每张图在顶部写明元信息作者、日期、对应版本、适用环境如 dev/test/prod。这些信息不是给渲染看的是给读者判断“这张图我还能不能信”的。图是活资产没有元信息的图三个月后就是一张废图。5.3 评审机制图和代码同步走 PR图和代码一样只有进入评审流程才具备约束力。我们团队的实践是任何涉及服务边界、接口设计、数据模型或部署架构的变更MR 里必须附带对应的图修改否则 CI 直接拦截。怎么拦截呢技术上可以用脚本检查指定目录的最后提交人和 MR 描述里的标签但更简单有效的做法是在 MR 模板里加一个必填章节“架构变更影响”要求变更人贴出修改前和修改后的图。改了一个接口两张时序图同时变化评审人一眼就能确认影响范围。有一次我评审一个缓存策略变更开发只改了代码没动图我在模板栏发现依赖关系图完全没有变化追回去一问原来是调用链里漏画了一个新的远程服务。这种错误恰好是评审机制存在的意义。5.4 图与代码一致性的自动化检测思路人肉检查图件和代码一致性始终不可靠所以我补充了一条半自动检测思路在关键图件旁边维护一个节点清单把服务、表、接口名都列出来再写一个简单的文本扫描脚本去代码库里检索这些名字是否存在。# 例从 docs 里提取图件中出现的服务名 grep -oE (订单服务|支付服务|库存服务) docs/architecture.md # 在服务代码目录里检索是否仍然存在 grep -rE 订单服务|支付服务|库存服务 services/ --include*.java /dev/null如果图里出现的名字代码库中完全找不到脚本就会输出告警。严格来说这还不是“图与代码完全一致”的保证但至少能抓住“图还在、代码没了”这类最典型的漂移。沿着这个思路还可以扩展服务数目对比、数据库表名前缀对比等。我建议每个团队根据自己的技术栈做定制不用追求大而全先抓最影响判断的异常。6. 实操过程与核心场景实现6.1 从零构建一张系统架构图的完整流程这里用一个模拟项目 X 作为例子走一遍完整流程。项目 X 是一个“订单中台”的简化版本包含前台订单入口、订单服务、库存服务、支付服务和消息队列。第一步确认核心对象。我在白板上列出所有参与系统运行的组件网关、订单服务、库存服务、支付服务、MQ、订单库、库存库、支付流水库。第二步确定连接关系。订单服务调库存服务和支付服务支付回调走 MQ 通知订单服务。第三步写入 Mermaidflowchart TB subgraph 接入 G[API网关] end subgraph 应用 O[订单服务] I[库存服务] P[支付服务] end subgraph 中间件 MQ[(消息队列)] end subgraph 数据 DB1[(订单库)] DB2[(库存库)] DB3[(支付流水库)] end G -- O G -- I G -- P O -- I O -- P O -- MQ P -- MQ O -- DB1 I -- DB2 P -- DB3第四步本地渲染验证。执行npx mmdc -i system/order-platform.md -o docs/order-platform.svg打开 SVG 检查布局。如果某些箭头交叉严重我会微调节点顺序或者增加 subgraph 层级。第五步提交 MR由另一位同事核对是否与当前服务划分一致。6.2 将图嵌入文档站点与团队 Wiki图的价值只有在被阅读的地方才能释放。我推荐的做法是把 Mermaid 图件和说明文档放在同一个 Markdown 文件里推送到代码托管平台后直接在页面上渲染。文档站点的 CI 构建流程中增加一步把渲染好的图件复制到站点图目录这样每个人看到的都是当前主干版本对应的图。对于团队内部 Wiki就用最原始可行的方式用 CI 生成菜单页索引定时推送最新渲染产物。这条链路的好处是团队 wiki 里的图永远来自主干代码不会出现“本地改了一版、线上还是旧图”的分裂情况。具体实现可以靠一条简单的 bash 命令完成批渲染for file in diagrams/**/*.md; do npx mmdc -i $file -o docs/$(basename $file .md).svg done6.3 多版本图件的管理与归档策略系统架构是会演进的。老版本的图有价值不能简单覆盖掉。我的策略是主干目录里只保留当前版本对应的图历史版本通过 Git 标签或分支归档。比如发布 v2.0.0 时在 diagrams 目录打一个 taggit tag -a diagrams-v2.0.0 -m order-platform architecture v2.0.0需要回溯当时系统长什么样时一句话就能切到历史快照git checkout diagrams-v2.0.0 -- diagrams/system/order-platform.md归档之后还要考虑到人眼查图的需求。我建议在 docs 目录维护一个 CHANGELOG记录每个版本架构图的核心变更比如“v2.0.0新增支付中心订单库拆分主从”。这样别人不用打开 diff 看图修改先读文字变更记录就能判断是否需要关注。7. 常见问题与排查技巧实录7.1 中文乱码问题中文乱码是我最早遇到的坑具体表现是图片渲染后中文变成方格或问号。原因基本都是渲染环境缺少中文字体。Mermaid CLI 渲染时依赖本机字体库如果目标机器或 CI 容器没有安装中文字体必然乱码。排查步骤第一步确认本地是否有可用中文字体macOS 用fc-list :langzhLinux 同样第二步安装字体Ubuntu 执行apt-get install fonts-noto-cjk第三步在 Mermaid 配置中指定字体族。把字体安装步骤写进 CI 构建脚本保证任何未知环境的机器渲染结果一致。# 示例CI 构建脚本片段中安装字体后渲染 - run: apt-get install -y fonts-noto-cjk - run: npx mmdc -i diagram.md -o diagram.svg7.2 节点重叠与连线混乱的调整技巧Mermaid 布局引擎在节点较多时偶尔出现重叠尤其是 flowchart 中既有横排又有纵排混合布局。我的经验是先尝试调整布局方向LR换成TB常常能解决大部分重叠问题。其次给不同层级节点使用 subgraph 强制分组让引擎的分组布局算法发挥作用。第三减少“旁路”边尽量避免一个节点同时连接很多远处的节点必要时可以用一个中间的聚合节点。如果还是乱八成是图本身过度耦合了。该拆图的时候就拆图把一张大图拆成几张带边界小图比硬调布局舒服太多了。这是设计问题不是工具问题。7.3 Git 冲突的合理解决思路多人同时维护同一张图时难免出现 Git 冲突。文本化图件的优势此时体现得淋漓尽致冲突区域可读、可解决。我的做法是先拉最新主干把冲突标记里的两个版本都看一遍确认谁改了什么。多数时候冲突只是两个人各自增加了一个新节点可以把两个节点都保留再手动调整连线。为了尽量减少冲突我还建议“谁改动谁负责清理”每个 MR 尽量只改一个主题相关的图不要顺手去格式化别人的图文件。格式化引起的假冲突最讨厌光看 diff 根本分不清是语义变化还是排版变化。7.4 大图渲染慢的性能优化当图节点超过一百个时渲染时间会呈指数上升。Mermaid CLI 本身性能有限。我的处理思路是拆分节点域每张图控制在 80 个节点以内同时在构建流程中把大型图降级为植物图——不追求实时预览只在主干合并后统一渲染并将渲染结果缓存到 CI 配置的缓存目录里。另外一个性能优化点是避免在文档预览里嵌入多个大图。VS Code 实时预览时如果同事的电脑性能一般大量 Mermaid 代码块会导致页面卡顿。我在文档开头加一个目录导航把不同图放在不同文档页中而不是全部堆在一个超长 README 里。8. 总结个人经验与后续扩展方向diagram-design 这趟实践下来最大的体会是“图不是画出来的是设计出来的”。这句话有两层意思一层是图的表达本身需要设计节点怎么定、边界怎么切、层次怎么分另一层是图的维护流程需要设计没有评审、没有版本、没有自动化的图最终一定会沦为没人信的“装饰品”。如果要给刚接触这套方法的团队一个起步建议我建议别贪多求全。先挑一个当前迭代一定会涉及的核心业务流程用 Mermaid 画一张流程图把图纳入当次 MR 的评审范畴。坚持两三个迭代后团队就会自然体会到“图代码化”在沟通成本和状态同步上的优势。这比一次引入几十个规范文件和一大堆工具链要可靠得多。基于现有的基础后面还可以往两个方向扩展一是把图作为领域文档的骨架连接需求文档、接口文档和运维文档形成真正完整的知识体系二是引入更智能的代码解析能力比如通过源码解析直接生成部分 UML 图或依赖图让“图服务代码更新”变成“图跟随代码生成”。这条路还有不少工程细节需要打磨但方向是明确且值得投入的。希望这篇实操记录能让你少踩几个我踩过的坑真正把 diagram-design 用成团队的一种基本功。
