Diagram as Code：用 Mermaid 画图的现代方式

引言：传统绘图工具的困境

作为开发者，你是否经历过这样的场景：

📊 鼠标拖拽的疲惫：在 Visio 或 Draw.io 里，反复调整组件位置，对齐线条，只为让图表看起来"专业"
💾 文件格式的噩梦：同事用 Mac 的 OmniGraffle 创建的文件，在你的 Windows 电脑上根本打不开
🤝 协作的困难：多人编辑同一张架构图时，不是覆盖就是冲突，最后只能通过截图和文字沟通
🔄 版本管理的无力：想查看上个月的系统设计图？抱歉，只能在一堆 架构图_v1.xml、架构图_v2_final.xml、架构图_v2_final_最终版.xml 中翻找

更糟糕的是，当业务需求变化，架构调整时，你需要重新打开那个沉重的 .vsdx 文件，再次经历鼠标拖拽的折磨。图表和代码分离，文档很快就过时了，团队成员对着三个月前的架构图一脸茫然："这个系统现在还是这样的吗？"

是时候改变了。

什么是 Diagram as Code？

Diagram as Code（图表即代码） 是一种现代化的图表创建理念：用代码描述图表，而不是用鼠标绘制。就像我们用代码描述基础设施（Infrastructure as Code）一样，我们也可以用代码来表达系统架构、业务流程、数据关系。

一个简单的例子，传统工具中你需要：

创建三个矩形框
分别命名为"用户"、"服务器"、"数据库"
用鼠标拖拽箭头连接它们
调整位置让它们看起来整齐

而在 Diagram as Code 中，你只需要写：

graph LR    用户 --> 服务器    服务器 --> 数据库

代码自动渲染成美观的流程图，布局由算法优化，你只需专注于内容本身。

这种理念的核心是：图表不再是静态的图片，而是可版本控制、可协作、可编程的代码。

Diagram as Code 的五大优势

1. 版本控制友好 📝

图表代码可以直接提交到 Git 仓库，每次修改都有清晰的 diff：

graph LR
    用户 --> 服务器
    服务器 --> 数据库
+   服务器 --> 缓存
+   缓存 --> 数据库

不再需要 v1、v2、v3_final_最终版 这样的文件命名混乱，Git 历史就是最好的版本记录。

2. 团队协作便捷 🤝

团队成员只需要文本编辑器，就能修改图表。合并冲突？用 Git 的三方合并工具轻松解决。不再需要担心"谁锁定了文件"或"覆盖了谁的修改"。

3. 可编程可自动化 🤖

图表代码可以通过脚本生成，可以集成到 CI/CD 流程中：

# 从数据库 schema 自动生成 ER 图
./generate-erd.sh | tee docs/database.mmd

# 在 CI 中验证图表语法
mermaid-cli --validate docs/**/*.mmd

想象一下，你的 API 文档中的序列图，可以从 OpenAPI 规范自动生成，永远不会过时。

4. 文档即代码（Docs as Code）📚

图表代码可以直接嵌入 Markdown 文档，和文字内容在同一个文件中：

## 系统架构

我们采用微服务架构：

```mermaid
graph TB
    Gateway --> ServiceA
    Gateway --> ServiceB
```

各服务职责如下...

这种方式让文档和图表紧密结合，不再需要在文档中插入图片链接，维护图片文件。

5. 快速迭代修改 ⚡

修改图表只需要编辑几行代码，而不是重新拖拽和调整。想添加一个新的服务？一行代码搞定。需要重命名某个组件？全局替换即可。

主流 Diagram as Code 工具对比

市面上有多种 Diagram as Code 工具，各有特色：

工具	优势	劣势	适用场景
Mermaid	语法简洁，生态完善，支持多种图表类型	样式定制相对受限	大多数技术文档、README、Wiki
PlantUML	功能强大，支持复杂的 UML 图	语法复杂，需要 Java 环境	详细的软件设计文档
Graphviz	底层强大，布局算法优秀	学习曲线陡峭，语法不够直观	学术论文、复杂图论可视化
D2	现代化设计，语法清晰	生态较新，工具支持较少	追求现代化体验的团队

对于大多数技术团队而言，Mermaid 是最佳选择。

Mermaid 为什么脱颖而出？

零配置渲染，开箱即用 🎁

Mermaid 最大的优势是生态支持：

GitHub/GitLab：原生支持，Markdown 中的 Mermaid 代码自动渲染
Notion/Obsidian：直接支持 Mermaid 语法
VSCode：丰富的插件支持实时预览
文档工具：VuePress、Docusaurus、MkDocs 等都内置支持

这意味着你的图表可以在几乎所有地方无缝显示，不需要额外的构建步骤。

语法直观易学 📖

Mermaid 的语法设计贴近自然语言，即使是非技术人员也能快速上手：

sequenceDiagram    Alice->>Bob: 你好，Bob！    Bob-->>Alice: 你好，Alice！

对比 PlantUML 的同样功能：

@startuml
Alice -> Bob: 你好，Bob！
Bob --> Alice: 你好，Alice！
@enduml

Mermaid 更加简洁，不需要额外的开始/结束标记。

图表类型丰富 🎨

Mermaid 支持 10+ 种图表类型，覆盖大多数使用场景：

流程图（Flowchart）
时序图（Sequence Diagram）
类图（Class Diagram）
状态图（State Diagram）
实体关系图（ER Diagram）
甘特图（Gantt Chart）
用户旅程图（User Journey）
Git 图（Git Graph）
饼图（Pie Chart）
思维导图（Mind Map）

社区活跃，持续进化 🚀

Mermaid 在 GitHub 上拥有 70k+ stars，社区活跃，新功能持续更新。遇到问题？Stack Overflow 和 GitHub Issues 上有大量讨论和解决方案。

实战示例：Mermaid 的强大之处

让我们通过几个实际例子，感受 Mermaid 的魅力。

示例 1：业务流程图 💼

代码：

flowchart TD    Start([用户访问]) --> Login{是否登录?}    Login -->|否| ShowLoginPage[显示登录页]    Login -->|是| CheckPermission{检查权限}        ShowLoginPage --> InputCredentials[输入凭证]    InputCredentials --> Validate{验证成功?}    Validate -->|否| ShowLoginPage    Validate -->|是| CheckPermission        CheckPermission -->|无权限| ShowError[显示错误]    CheckPermission -->|有权限| ShowDashboard[显示仪表盘]        ShowError --> End([结束])    ShowDashboard --> End        style Start fill:#e1f5ff    style End fill:#ffe1e1    style ShowDashboard fill:#e1ffe1

渲染效果说明： 这个流程图清晰展示了用户访问系统的完整流程，包括登录验证、权限检查等关键步骤。通过不同的颜色（开始节点为蓝色，结束节点为红色，成功状态为绿色），让流程的逻辑一目了然。

示例 2：API 调用序列图 🔄

代码：

sequenceDiagram    participant Client as 客户端    participant Gateway as API 网关    participant Auth as 认证服务    participant Service as 业务服务    participant DB as 数据库        Client->>Gateway: POST /api/orders    activate Gateway    Gateway->>Auth: 验证 Token    activate Auth    Auth-->>Gateway: Token 有效    deactivate Auth        Gateway->>Service: 创建订单    activate Service    Service->>DB: 插入订单记录    activate DB    DB-->>Service: 订单 ID    deactivate DB        Service->>Service: 发送订单通知    Service-->>Gateway: 订单创建成功    deactivate Service        Gateway-->>Client: 200 OK + 订单详情    deactivate Gateway

渲染效果说明： 序列图展示了多个服务之间的时序交互。activate/deactivate 关键字让调用栈的层次清晰可见，箭头样式（->> 实线，-->> 虚线）区分了请求和响应，帮助读者理解异步处理流程。

示例 3：系统架构图 🏗️

代码：

graph TB    subgraph "前端层"        Web[Web 应用]        Mobile[移动应用]    end        subgraph "网关层"        Gateway[API 网关<br>负载均衡]    end        subgraph "服务层"        AuthService[认证服务]        OrderService[订单服务]        PaymentService[支付服务]        NotifyService[通知服务]    end        subgraph "数据层"        MySQL[(MySQL<br>主数据库)]        Redis[(Redis<br>缓存)]        MongoDB[(MongoDB<br>日志)]    end        Web --> Gateway    Mobile --> Gateway    Gateway --> AuthService    Gateway --> OrderService    Gateway --> PaymentService        OrderService --> MySQL    OrderService --> Redis    PaymentService --> MySQL    AuthService --> Redis        OrderService -.消息队列.-> NotifyService    NotifyService --> MongoDB        style Gateway fill:#fff4e6    style MySQL fill:#e6f3ff    style Redis fill:#ffe6e6

渲染效果说明： 通过 subgraph 将系统分层，不同的连线样式（实线表示同步调用，虚线表示异步消息）清晰表达了架构的层次关系。颜色编码让每一层的职责更加直观。

Diagram as Code 的挑战

尽管 Diagram as Code 有诸多优势，但也面临一些挑战：

1. 初学者学习成本 📚

对于不熟悉代码的团队成员（产品经理、UI 设计师），学习语法可能需要时间。虽然 Mermaid 语法简单，但仍然需要记忆关键字和结构。

2. 复杂图表的代码可读性 🤔

当图表变得复杂（比如包含 50+ 个节点的架构图），代码行数也会增加，可能难以一眼看出整体结构。这时需要良好的代码组织和注释。

3. 实时预览需求 👀

编写图表代码时，开发者希望能实时看到渲染效果，而不是"写代码 → 保存 → 刷新浏览器"的循环。虽然有 VSCode 插件，但体验不够流畅。

4. 样式定制化难度 🎨

Mermaid 的默认样式已经很美观，但如果需要深度定制（比如匹配公司 VI 规范），通过代码配置主题相对复杂，不如可视化工具直观。

MermaidKit：让 Diagram as Code 更简单

正是为了解决这些挑战，我们开发了 MermaidKit。

MermaidKit 是一个专为 Mermaid 设计的在线工具平台，让 Diagram as Code 的体验更加流畅：

🚀 实时预览，所见即所得

告别"编辑-保存-刷新"的循环。在 MermaidKit 中，你的每一次代码修改都会立即渲染，左侧写代码，右侧看效果，就像使用可视化工具一样直观。

💡 智能补全，降低学习成本

不记得 Mermaid 的语法？没关系。MermaidKit 提供智能代码补全和语法提示，输入 seq 就能自动展开完整的序列图模板，还有内置的代码片段库，常用图表一键插入。

🎨 样式定制，轻松调整

通过可视化的主题编辑器，你可以轻松调整颜色、字体、线条样式，无需手写复杂的 CSS。定制好的主题可以保存为模板，在团队内共享。

🤝 团队协作，共享知识

将你的图表发布为公开链接，团队成员无需注册即可查看。支持评论和版本历史，让图表演进过程可追溯。你还可以创建图表集合，将相关的架构图、流程图组织在一起。

📤 多格式导出，灵活使用

除了复制 Mermaid 代码，MermaidKit 还支持导出为 PNG、SVG、PDF，方便在各种场合使用。生成的图片自动优化尺寸和分辨率，确保清晰美观。

访问 https://mermaidkit.com 立即体验，让 Diagram as Code 真正为你所用。

结语：拥抱图表的代码化未来

Diagram as Code 不仅仅是一种工具选择，更是一种理念转变——将图表纳入代码世界，享受版本控制、协作、自动化的红利。

就像基础设施从手动配置走向 Infrastructure as Code，文档从 Word 走向 Docs as Code 一样，图表也正在经历同样的变革。在这个变革中，Mermaid 凭借其简洁的语法和广泛的生态支持，成为了最受欢迎的选择。

如果你还在为维护庞大的 Visio 文件而头疼，如果你的团队还在为图表协作而苦恼，不妨试试 Diagram as Code。从今天开始，在你的 README.md 中嵌入第一张 Mermaid 流程图，感受纯文本绘图的魅力。

当你爱上这种方式，也别忘了访问 MermaidKit，让工具进一步提升你的效率。

让我们一起，用代码绘制更美好的世界。 🚀

引言：传统绘图工具的困境

作为开发者，你是否经历过这样的场景：

📊 鼠标拖拽的疲惫：在 Visio 或 Draw.io 里，反复调整组件位置，对齐线条，只为让图表看起来"专业"
💾 文件格式的噩梦：同事用 Mac 的 OmniGraffle 创建的文件，在你的 Windows 电脑上根本打不开
🤝 协作的困难：多人编辑同一张架构图时，不是覆盖就是冲突，最后只能通过截图和文字沟通
🔄 版本管理的无力：想查看上个月的系统设计图？抱歉，只能在一堆 架构图_v1.xml、架构图_v2_final.xml、架构图_v2_final_最终版.xml 中翻找

是时候改变了。

什么是 Diagram as Code？

一个简单的例子，传统工具中你需要：

创建三个矩形框
分别命名为"用户"、"服务器"、"数据库"
用鼠标拖拽箭头连接它们
调整位置让它们看起来整齐

而在 Diagram as Code 中，你只需要写：

graph LR
    用户 --> 服务器
    服务器 --> 数据库

graph LR    用户 --> 服务器    服务器 --> 数据库

代码自动渲染成美观的流程图，布局由算法优化，你只需专注于内容本身。

这种理念的核心是：图表不再是静态的图片，而是可版本控制、可协作、可编程的代码。

Diagram as Code 的五大优势

1. 版本控制友好 📝

图表代码可以直接提交到 Git 仓库，每次修改都有清晰的 diff：

graph LR
    用户 --> 服务器
    服务器 --> 数据库
+   服务器 --> 缓存
+   缓存 --> 数据库

不再需要 v1、v2、v3_final_最终版 这样的文件命名混乱，Git 历史就是最好的版本记录。

2. 团队协作便捷 🤝

团队成员只需要文本编辑器，就能修改图表。合并冲突？用 Git 的三方合并工具轻松解决。不再需要担心"谁锁定了文件"或"覆盖了谁的修改"。

3. 可编程可自动化 🤖

图表代码可以通过脚本生成，可以集成到 CI/CD 流程中：

# 从数据库 schema 自动生成 ER 图
./generate-erd.sh | tee docs/database.mmd

# 在 CI 中验证图表语法
mermaid-cli --validate docs/**/*.mmd

想象一下，你的 API 文档中的序列图，可以从 OpenAPI 规范自动生成，永远不会过时。

4. 文档即代码（Docs as Code）📚

图表代码可以直接嵌入 Markdown 文档，和文字内容在同一个文件中：

## 系统架构

我们采用微服务架构：

```mermaid
graph TB
    Gateway --> ServiceA
    Gateway --> ServiceB
```

各服务职责如下...

这种方式让文档和图表紧密结合，不再需要在文档中插入图片链接，维护图片文件。

5. 快速迭代修改 ⚡

修改图表只需要编辑几行代码，而不是重新拖拽和调整。想添加一个新的服务？一行代码搞定。需要重命名某个组件？全局替换即可。

主流 Diagram as Code 工具对比

市面上有多种 Diagram as Code 工具，各有特色：

工具	优势	劣势	适用场景
Mermaid	语法简洁，生态完善，支持多种图表类型	样式定制相对受限	大多数技术文档、README、Wiki
PlantUML	功能强大，支持复杂的 UML 图	语法复杂，需要 Java 环境	详细的软件设计文档
Graphviz	底层强大，布局算法优秀	学习曲线陡峭，语法不够直观	学术论文、复杂图论可视化
D2	现代化设计，语法清晰	生态较新，工具支持较少	追求现代化体验的团队

对于大多数技术团队而言，Mermaid 是最佳选择。

Mermaid 为什么脱颖而出？

零配置渲染，开箱即用 🎁

Mermaid 最大的优势是生态支持：

GitHub/GitLab：原生支持，Markdown 中的 Mermaid 代码自动渲染
Notion/Obsidian：直接支持 Mermaid 语法
VSCode：丰富的插件支持实时预览
文档工具：VuePress、Docusaurus、MkDocs 等都内置支持

这意味着你的图表可以在几乎所有地方无缝显示，不需要额外的构建步骤。

语法直观易学 📖

Mermaid 的语法设计贴近自然语言，即使是非技术人员也能快速上手：

sequenceDiagram
    Alice->>Bob: 你好，Bob！
    Bob-->>Alice: 你好，Alice！

sequenceDiagram    Alice->>Bob: 你好，Bob！    Bob-->>Alice: 你好，Alice！

对比 PlantUML 的同样功能：

@startuml
Alice -> Bob: 你好，Bob！
Bob --> Alice: 你好，Alice！
@enduml

Mermaid 更加简洁，不需要额外的开始/结束标记。

图表类型丰富 🎨

Mermaid 支持 10+ 种图表类型，覆盖大多数使用场景：

流程图（Flowchart）
时序图（Sequence Diagram）
类图（Class Diagram）
状态图（State Diagram）
实体关系图（ER Diagram）
甘特图（Gantt Chart）
用户旅程图（User Journey）
Git 图（Git Graph）
饼图（Pie Chart）
思维导图（Mind Map）

flowchart TD
    Start([用户访问]) --> Login{是否登录?}
    Login -->|否| ShowLoginPage[显示登录页]
    Login -->|是| CheckPermission{检查权限}
    
    ShowLoginPage --> InputCredentials[输入凭证]
    InputCredentials --> Validate{验证成功?}
    Validate -->|否| ShowLoginPage
    Validate -->|是| CheckPermission
    
    CheckPermission -->|无权限| ShowError[显示错误]
    CheckPermission -->|有权限| ShowDashboard[显示仪表盘]
    
    ShowError --> End([结束])
    ShowDashboard --> End
    
    style Start fill:#e1f5ff
    style End fill:#ffe1e1
    style ShowDashboard fill:#e1ffe1

flowchart TD    Start([用户访问]) --> Login{是否登录?}    Login -->|否| ShowLoginPage[显示登录页]    Login -->|是| CheckPermission{检查权限}        ShowLoginPage --> InputCredentials[输入凭证]    InputCredentials --> Validate{验证成功?}    Validate -->|否| ShowLoginPage    Validate -->|是| CheckPermission        CheckPermission -->|无权限| ShowError[显示错误]    CheckPermission -->|有权限| ShowDashboard[显示仪表盘]        ShowError --> End([结束])    ShowDashboard --> End        style Start fill:#e1f5ff    style End fill:#ffe1e1    style ShowDashboard fill:#e1ffe1

示例 2：API 调用序列图 🔄

代码：

sequenceDiagram
    participant Client as 客户端
    participant Gateway as API 网关
    participant Auth as 认证服务
    participant Service as 业务服务
    participant DB as 数据库
    
    Client->>Gateway: POST /api/orders
    activate Gateway
    Gateway->>Auth: 验证 Token
    activate Auth
    Auth-->>Gateway: Token 有效
    deactivate Auth
    
    Gateway->>Service: 创建订单
    activate Service
    Service->>DB: 插入订单记录
    activate DB
    DB-->>Service: 订单 ID
    deactivate DB
    
    Service->>Service: 发送订单通知
    Service-->>Gateway: 订单创建成功
    deactivate Service
    
    Gateway-->>Client: 200 OK + 订单详情
    deactivate Gateway

sequenceDiagram    participant Client as 客户端    participant Gateway as API 网关    participant Auth as 认证服务    participant Service as 业务服务    participant DB as 数据库        Client->>Gateway: POST /api/orders    activate Gateway    Gateway->>Auth: 验证 Token    activate Auth    Auth-->>Gateway: Token 有效    deactivate Auth        Gateway->>Service: 创建订单    activate Service    Service->>DB: 插入订单记录    activate DB    DB-->>Service: 订单 ID    deactivate DB        Service->>Service: 发送订单通知    Service-->>Gateway: 订单创建成功    deactivate Service        Gateway-->>Client: 200 OK + 订单详情    deactivate Gateway

示例 3：系统架构图 🏗️

代码：

graph TB
    subgraph "前端层"
        Web[Web 应用]
        Mobile[移动应用]
    end
    
    subgraph "网关层"
        Gateway[API 网关<br>负载均衡]
    end
    
    subgraph "服务层"
        AuthService[认证服务]
        OrderService[订单服务]
        PaymentService[支付服务]
        NotifyService[通知服务]
    end
    
    subgraph "数据层"
        MySQL[(MySQL<br>主数据库)]
        Redis[(Redis<br>缓存)]
        MongoDB[(MongoDB<br>日志)]
    end
    
    Web --> Gateway
    Mobile --> Gateway
    Gateway --> AuthService
    Gateway --> OrderService
    Gateway --> PaymentService
    
    OrderService --> MySQL
    OrderService --> Redis
    PaymentService --> MySQL
    AuthService --> Redis
    
    OrderService -.消息队列.-> NotifyService
    NotifyService --> MongoDB
    
    style Gateway fill:#fff4e6
    style MySQL fill:#e6f3ff
    style Redis fill:#ffe6e6

graph TB    subgraph "前端层"        Web[Web 应用]        Mobile[移动应用]    end        subgraph "网关层"        Gateway[API 网关<br>负载均衡]    end        subgraph "服务层"        AuthService[认证服务]        OrderService[订单服务]        PaymentService[支付服务]        NotifyService[通知服务]    end        subgraph "数据层"        MySQL[(MySQL<br>主数据库)]        Redis[(Redis<br>缓存)]        MongoDB[(MongoDB<br>日志)]    end        Web --> Gateway    Mobile --> Gateway    Gateway --> AuthService    Gateway --> OrderService    Gateway --> PaymentService        OrderService --> MySQL    OrderService --> Redis    PaymentService --> MySQL    AuthService --> Redis        OrderService -.消息队列.-> NotifyService    NotifyService --> MongoDB        style Gateway fill:#fff4e6    style MySQL fill:#e6f3ff    style Redis fill:#ffe6e6

让我们一起，用代码绘制更美好的世界。 🚀

作者

分类

Diagram as Code：用 Mermaid 画图的现代方式

作者

分类