Mermaid详解：用文本描述生成各种漂亮图表

在软件开发、项目管理和技术文档编写中，图表是传达复杂信息、说明系统架构、业务流程或交互逻辑的强大工具。然而，传统上绘制图表往往需要专门的图形编辑软件，操作繁琐，不易版本控制，也难以在文本文件中直接嵌入。这时，Mermaid 应运而生。Mermaid 是一个基于 JavaScript 的库，它允许你使用简单的类 Markdown 文本语法来定义和渲染各种图表，并将其嵌入到 Markdown、HTML 或其他 Web 环境中。它极大地简化了图表的创建、维护和版本控制，是现代文档编写的利器。

“Mermaid 的核心思想是‘图表即代码’。这意味着你可以像编写代码一样编写图表的逻辑，从而实现图表的版本控制、自动化生成和轻松分享。它让复杂的可视化变得触手可及。”

---

一、Mermaid 简介

• 官方网站：mermaid.live (在线编辑器)
• GitHub 仓库：mermaid-js/mermaid

Mermaid 是一款基于 JavaScript 的图表绘制工具，它采用文本描述语言来定义图表结构，然后将其渲染成 SVG 或 PNG 格式的图形。它的目标是：

• 简化图表创建：告别繁琐的拖放操作，只需编写简单的文本。
• 易于维护和版本控制：图表的定义是纯文本，可以轻松地存储在 Git 等版本控制系统中。
• 高度可嵌入：可以无缝集成到 Markdown 文件、GitHub Pages、Jira、Confluence、Visual Studio Code 等多种平台和工具中。
• 支持多种图表类型：包括流程图、时序图、类图、状态图、甘特图等。

二、Mermaid 的基本语法与使用

Mermaid 图表的文本定义通常被包含在特定的代码块中。在 Markdown 文件中，这意味着使用 mermaid 语言标识符：

Mermaid效果Markdown语法

graph TD
    A[开始] --> B(处理中)
    B --> C{条件判断}
    C -- 是 --> D[成功]
    C -- 否 --> E[失败]
    D --> F[结束]
    E --> F

在支持 Mermaid 的环境中（如 GitHub Pages、VS Code 预览、Jira 等），或者通过 Mermaid JS 库在 HTML 页面中渲染时，上述代码块就会被转换为一个漂亮的流程图。

2.1 常见的图表类型及示例

2.1.1 流程图 (Flowchart) - graph

流程图是 Mermaid 最常用的功能之一，用于描述过程和工作流。

• 方向：graph TD (上到下), graph LR (左到右), graph TB (上到下), graph RL (右到左), graph BT (下到上)。
• 节点形状：
  • A[方形]：默认矩形。
  • B(圆角矩形)。
  • C{{菱形}}：条件判断。
  • D>旗形]：子程序/处理。
  • E((圆形))：开始/结束。
    F[/倾斜\]：输入/输出。
  • G[\倾斜/]
  • H[(Cylinder)]：数据库
  • I[[跑道形]]：并行
• 连接线：
  • -->：箭头线。
  • ---：直线。
  • -- 文本 -->：带文本的箭头线。
  • -.->：虚线箭头。
  • --o：圆形箭尾。
  • --x：叉形箭尾。

示例：用户登录流程

Mermaid效果Markdown语法

graph TD
    A[用户访问登录页] --> B{输入用户名/密码};
    B -- 点击登录 --> C(发送登录请求);
    C --> D{认证服务器验证凭据};
    D -- 凭据无效 --> E(显示错误信息);
    E --> B;
    D -- 凭据有效 --> F[生成会话/Token];
    F --> G[重定向到首页];

2.1.2 时序图 (Sequence Diagram) - sequenceDiagram

时序图用于描述对象之间消息传递的时间顺序，常用于展示系统交互。

• 参与者：participant A (参与者名称)，actor B (角色)。
• 消息发送：
  • A->B: 消息内容：实线箭头。
  • A-->B: 消息内容：虚线箭头。
  • A->>B: 异步消息：开放箭头。
  • A-->>B: 异步虚线消息。
• 激活/去激活：activate A / deactivate A。
• 循环：loop ... end。
• 可选：alt ... else ... end。
• 注释：Note left of A: 注释内容。

示例：微服务订单创建

Mermaid效果：

Markdown语法：

sequenceDiagram
    actor 用户
    participant 客户端
    participant 订单服务
    participant 库存服务
    participant 支付服务

    用户->>客户端: 提交订单
    客户端->>订单服务: 创建订单(商品ID, 数量)
    activate 订单服务
    订单服务->>库存服务: 扣减库存(商品ID, 数量)
    activate 库存服务
    库存服务-->>订单服务: 扣减成功/失败
    deactivate 库存服务

    alt 扣减成功
        订单服务->>支付服务: 发起支付(订单ID, 金额)
        activate 支付服务
        支付服务-->>订单服务: 支付成功/失败
        deactivate 支付服务

        alt 支付成功
            订单服务-->>客户端: 订单创建成功，等待发货
            客户端->>用户: 订单创建成功提示
        else 支付失败
            订单服务->>库存服务: 回滚库存(商品ID, 数量)
            订单服务-->>客户端: 订单创建失败，支付问题
            客户端->>用户: 订单创建失败提示
        end
    else 扣减失败
        订单服务-->>客户端: 订单创建失败，库存不足
        客户端->>用户: 库存不足提示
    end
    deactivate 订单服务

2.1.3 类图 (Class Diagram) - classDiagram

类图用于展示类、接口以及它们之间的关系。

• 类定义：class 类名 { 成员变量 方法 }
  • + (public), - (private), # (protected), ~ (package/internal)。
• 关系：
  • <|-- (继承/实现)
  • *-- (组合)
  • o-- (聚合)
  • --> (关联)
  • ..> (依赖)
  • ..|> (实现，虚线箭头)

示例：基本电商系统类图

Mermaid效果：

Markdown语法：

classDiagram
    class User {
        +String userId
        +String username
        +String email
        +login()
        +logout()
    }

    class Product {
        +String productId
        +String name
        +double price
        +int stock
        +getProductInfo()
    }

    class Order {
        -String orderId
        -String userId
        -Date orderDate
        -List<OrderItem> items
        +totalAmount()
        +placeOrder(User u, List<OrderItem> items)
    }

    class OrderItem {
        -String itemId
        -String productId
        -int quantity
        -double unitPrice
        +calculateSubtotal()
    }

    User "1" --> "*" Order : placed by
    Order "1" *-- "*" OrderItem : contains
    OrderItem "1" --> "1" Product : refers to

2.1.4 状态图 (State Diagram) - stateDiagram-v2

状态图描述一个对象在其生命周期中可能经历的各种状态和状态转换。

• 状态：state "名称"
• 初始状态：[*] --> State
• 转换：State1 --> State2: Event触发 / [条件] 动作
• 复合状态：state P { StateA --> StateB }

示例：订单生命周期

Mermaid效果：

Markdown语法：

stateDiagram-v2
    [*] --> PendingPayment
    PendingPayment --> Paid: PaymentReceived
    Paid --> Processing: OrderConfirmed
    Processing --> Shipped: ItemsPacked
    Shipped --> Delivered: InTransit / [CustomerSigned]
    Delivered --> [*]: OrderCompleted

    Paid --> Canceled: PaymentRefunded / [UserCancel]
    PendingPayment --> Canceled: PaymentTimeout

2.1.5 甘特图 (Gantt Chart) - gantt

甘特图用于项目管理，展示任务、进度和时间线。

• 格式：dateFormat YYYY-MM-DD，title 项目名称
• 任务定义：任务名称 : ID, 状态, 开始日期, 持续天数/结束日期
  • active (进行中), done (完成), crit (关键任务), after ID (依赖前一个任务)

示例：项目开发计划

Mermaid效果：

Markdown语法：

gantt
    dateFormat  YYYY-MM-DD
    title       Web 应用开发计划

    section 需求分析
    S1 :des1, 2024-04-10, 5d
    S2 :des2, after S1, 3d

    section 后端开发
    B1 :active, 2024-04-15, 7d
    B2 :crit, after B1, 10d

    section 前端开发
    F1 :active, 2024-04-18, 8d
    F2 :after F1, 12d

    section 测试与部署
    T1 :done, 2024-04-29, 5d
    D1 :after T1, 3d

2.2 小提示和配置

• 主题 (Themes)：Mermaid 支持多种主题，如 default, dark, forest, neutral, base。可以在代码块顶部或通过配置全局设置：
  Mermaid效果：
  Markdown语法：

%%{init: {'theme': 'dark'}}%%
 graph TD
     A-->B

• 样式定制：可以通过 CSS 选择器对生成的 SVG 进行样式定制，或者在 Mermaid 配置中修改颜色等。
• 官方在线编辑器：mermaid.live 是一个非常棒的工具，可以实时预览你的 Mermaid 代码，并导出图片。

三、Mermaid 的集成与使用场景

Mermaid 的强大之处在于其广泛的集成能力：

1. Markdown 文件：最常见的用法，直接在 Markdown 文档中嵌入代码块。
2. GitHub / GitLab：GitHub Pages、GitHub Readme 和 GitLab 均原生支持 Mermaid 渲染。
3. Visual Studio Code：配合插件（如 Markdown Preview Enhanced），可以在 VS Code 中实时预览 Mermaid 图表。
4. Jira / Confluence：部分插件或最新版本已支持 Mermaid。
5. Notion：Notion 的代码块支持 Mermaid 渲染。
6. 静态网站生成器：如 Jekyll, Hugo, Hexo 等，可以通过集成 Mermaid JS 库来实现图表渲染。
7. Web 应用：任何 Web 应用都可以在前端集成 Mermaid JS 库，动态渲染用户输入的图表代码。
8. 文档工具：如 Sphinx、Docusaurus 等，都有相应的 Mermaid 扩展。

四、为什么选择 Mermaid？

• 版本控制友好：图表作为纯文本，可以轻松地进行版本管理、代码审查和合并，避免了二进制文件冲突的麻烦。
• 高效率：通过复制粘贴和少量修改即可快速生成相似图表，比图形工具快得多。
• 平台无关性：只要支持 Markdown 和 Mermaid 的渲染，你的图表就能随处可见。
• 降低学习成本：语法直观，上手快。
• 代码即文档：将图表与代码或文档本身紧密结合，提升文档的“活”性。
• 自动化潜力：理论上可以从代码或数据结构自动生成 Mermaid 字符串，实现图表的自动化。

五、总结

Mermaid 是现代技术文档和项目沟通的强大工具。它通过“图表即代码”的理念，彻底改变了我们创建和维护图表的方式。无论你是开发者、项目经理还是技术作家，学习和掌握 Mermaid 都能显著提升你的工作效率和文档质量。告别繁琐的图形编辑，拥抱文本定义的强大和便捷吧！