Back to Blog

用 Mermaid + 自定义脚本生成可验证的动态架构图（附 YAML DSL 示例）

2026/8/29

用 Mermaid + 自定义脚本生成可验证的动态架构图

做系统架构设计时，我最头疼的不是画图，而是图的「可信度」。

以前我们习惯用 PPT、Visio 或者 draw.io 导出一张 PNG。图是好看，但每次系统重构，图就跟不上了。代码改了，架构图还是三个月前的版本。更致命的是，这种静态图是「黑盒」——读者无法验证连线到底对不对，节点含义是否准确，逻辑是否自洽。

最近我在团队内部推广一种新的流程：基于 Mermaid 图表库配合自定义 JavaScript，生成动态的、可交互的架构图。它的核心优势不是「画得快」，而是「可验证」和「自包含」。

为什么我们需要「可验证」的图

传统的静态架构图有一个隐性缺陷：它暗示了一种「终结态」。读者会默认这张图是权威的、最新的。但现实是，微服务架构、容器化部署让系统拓扑变化极快。

我们的思路反过来了。生成的不是图片，而是一个自包含的 HTML 文件。这个文件里既有 Mermaid 渲染逻辑，也有数据描述。这意味着：

  1. 所见即所得的动态效果：Mermaid 原生支持 flowchart 和 sequenceDiagram，配合少量 CSS 动画可实现节点的呼吸动效或连线流向。这些动效不是花哨的装饰，而是信息载体——比如数据流的实时方向、服务的健康状态提示。
  2. 可交互验证：通过挂载点击事件，点击任意服务节点可展开详情或查看依赖链。读者不再是被动接受一张图，而是可以主动「探索」架构。这种参与感让错误更容易被发现——同事看到某个不该连接的线连上了，会立刻提出来。
  3. 单一文件分发：整个架构图就是一个 .html 文件，引入本地或 CDN 的 Mermaid 库即可渲染。发给老板或客户，他们直接双击打开，浏览器兼容性好，打印 PDF 也清晰。

核心能力：从 DSL 到精美容器

我们不鼓励纯拖拽式的绘图方式，而是鼓励写声明式的数据结构（类似 YAML 或 JSON 描述的节点与边），然后通过脚本转换为 Mermaid 语法，最后渲染为图表。

这让我想到了用 Git 管理文档的思路：图即代码。

你可以把架构描述文件放在版本控制里。当 PR 合并，架构变更就有迹可循。对比上次提交的 diff，就能清楚知道哪些服务解耦了、哪些链路新增了。

支持的图类型

除了常规的架构图，Mermaid 还擅长处理几种容易画错的类型：

  • 工作流图：展示用户旅程或服务触发链，时序感强。
  • 序列图：清晰的异步调用关系，语法简洁易维护。
  • 数据流图：高亮核心数据路径，一眼看出瓶颈。
  • 生命周期图：描述对象或状态机的变迁过程。

YAML DSL 示例

以下是一个简化的 YAML 配置示例，用于定义节点和边的关系：

graph: flowchart LR
  subgraph services
    A[用户服务]
    B[订单服务]
    C[支付网关]
  end
  A -->|发起订单| B
  B -->|请求支付| C

通过一个轻量的 Node.js 脚本，可以将此 YAML 解析并注入到 HTML 模板中，最终输出为独立的 .html 文件。

落地实践：如何融入开发流程

在兰屿星奇（一家专注云原生系统定制开发的技术团队）的实践中，我们是这样用的：

  1. 设计阶段：用 Markdown 或 YAML 写下核心组件和关系，通过本地脚本预览 Mermaid 渲染效果。
  2. 评审阶段：将生成的 HTML 文件作为附件发在评审文档里。评审人可以直接在浏览器中打开，通过缩放、点击等方式查看细节。
  3. 交付阶段：导出最终版的自包含 HTML，嵌入到技术白皮书或客户演示材料中。相比 PPT，这个 HTML 在投影仪上展示时，动态效果能更好地辅助讲解。

导出与分享

它的导出功能很干净。你可以导出高清 PNG（用于打印）、PDF（用于归档），或者直接保留 HTML 用于交互展示。

所有渲染逻辑都依赖标准的浏览器环境，无需联网加载重型 JS/CSS 库，这点对于涉及敏感架构信息的企业客户非常重要。

总结

架构图文档不应该是一次性的装饰品，而应该是系统事实的来源之一。

基于 Mermaid 和自定义脚本的方案，用技术的手段（动态渲染、交互验证、版本化管理）解决了传统绘图工具无法解决的「信任」问题。当一张图可以被阅读、被交互、被 diff 时，它就成为了团队沟通的高效工具，而不仅仅是一张好看的插画。

如果你正在为微服务架构图的维护成本头疼，不妨试试这种「可验证」的思路。