Mermaid 详解与实践

一、Mermaid 概述

Mermaid 是一种基于文本的图表绘制语言，它巧妙地融合在 Markdown 文档里，让使用者无需复杂的图形编辑软件，仅靠敲代码就能生成专业美观的各类图表。这一特性使得它在技术写作、项目文档、知识分享等领域迅速走红，为可视化表达流程、架构、时间安排等信息提供了高效途径。

https://mermaid.nodejs.cn/intro/

二、Mermaid 基础语法详解

（一）流程图（Flowcharts）

1. 图的初始化与方向设定
   • 使用graph关键字开启流程图绘制之旅，紧接着的方向标识决定了整个流程图的布局走向。例如，graph TD，其中 “TD” 代表 “Top - Down”，也就是自上而下的布局；graph LR意味着从左到右布局，这种设定为后续节点排列锚定了框架。
   • 代码示例：

graph TD;

1. 节点创建
   • 普通节点：用方括号[]来界定普通节点内容，比如A[任务A]，“任务 A” 就是在最终图表里呈现出来的节点文本。这种节点常用于表示流程里的一个具体步骤或者操作。
   • 决策节点：菱形括号{}用于构建决策节点，例如B{条件判断}，当流程运行到该节点时，需要依据某个条件决定后续走向，天生带有分支属性。
   • 代码示例：

graph TD;
    start[项目开始] --> decision{继续与否?};

1. 连线与流向
   • 基本的连线通过-->来搭建，它将不同节点按顺序或者逻辑关系串联起来，形成流程脉络。如果想要在连线上添加注释，语法是--|注释文字|>，例如A -->|提交审核| B，能让流程的过渡信息更明晰。
   • 代码示例：

graph TD;
    task1[完成初稿] -->|送审| review{审核通过?};
    review -->|是| publish[发布];
    review -->|否| revise[修改];

1. 子图应用
   • 当流程变得复杂，subgraph就派上用场了。它允许把一部分相关节点和连线封装成子图，让主图结构更清晰。子图有自己的名称，内部按照常规的节点、连线规则绘制。
   • 代码示例：

mermaid

graph TD;
    main_start[主流程开始] --> sub1;
    subgraph sub1
    sub_start[子流程开始] --> task1[子任务1] --> task2[子任务2];
    end
    sub1 --> main_end[主流程结束];

（二）时序图（Sequence Diagrams）

1. 起始声明
   • 一切从sequenceDiagram关键字开始，它宣告了时序图绘制的开端，后续所有元素都在这个框架下有序添加。
   • 代码示例：

sequenceDiagram

1. 参与者定义
   • 用participant逐一介绍参与交互过程的角色，这些角色可以是人、系统组件或者服务等。例如participant User、participant Server，多个参与者并排罗列，构成了交互的主体阵容。
   • 代码示例：

sequenceDiagram
    participant FrontEnd
    participant BackEnd

1. 消息传递
   • 同步消息：同步消息传递时，发送方等待接收方回应才推进流程，用->>表示，格式为发送方 ->> 接收方: 消息内容。比如FrontEnd ->> BackEnd: 请求数据。
   • 异步消息：异步消息则不依赖即时回应，发送方发完就继续，用-->>表示，例如BackEnd -->> Database: 异步写入。
   • 激活时段：使用activate和deactivate标记某个角色处于忙碌、交互活跃的时间段。activate FrontEnd开启激活，deactivate FrontEnd结束激活。
   • 代码示例：

sequenceDiagram
    participant FrontEnd
    participant BackEnd
    participant Database

    FrontEnd->>BackEnd: 发起请求
    activate BackEnd
    BackEnd->>Database: 查询数据
    Database-->>BackEnd: 返回数据
    BackEnd-->>FrontEnd: 响应数据
    deactivate BackEnd

（三）甘特图（Gantt Charts）

1. 初始化与时间格式
   • 以gantt关键字启动甘特图绘制，紧接要定义时间格式，常用dateFormat YYYY - MM - DD，这确保后续安排任务时间时能精准匹配日期规范。
   • 代码示例：

gantt
    dateFormat YYYY-MM-DD

1. 任务定义

   • 任务在甘特图里遵循任务名称 :任务ID, 开始时间, 持续时长这样的格式。任务 ID 起到关联任务、设置先后顺序与依赖关系的作用。例如任务1 :a1, 2025-01-01, 3d，意味着任务 1 从 2025 年 1 月 1 日开始，持续 3 天。

   • 代码示例：

     gantt
         dateFormat YYYY-MM-DD
         title 项目任务安排
         section 前期任务
             需求调研 :a1, 2025-01-01, 5d
             方案设计 :a2, after a1, 7d
     

1. 任务依赖
   • 除了简单按时间先后排列，还能设置任务间的依赖关系。用after关键字关联任务 ID，就能表明某个任务要在前一个任务完成之后才启动。
   • 代码示例：

gantt
    dateFormat YYYY-MM-DDD
    title 软件开发项目
    section 开发
        模块A开发 :a1, 2025-01-01, 10d
        模块B开发 :a2, after a1, 15d

（四）类图（Class Diagrams）

1. 类的定义
   • 从classDiagram开启类图绘制大门，类内部属性和方法按照特定语法书写。对于属性，用+表示 public 属性，-表示 private 属性，例如class Car {+speed : int}，这里定义了一个 Car 类，有一个 public 的 speed 属性。
   • 代码示例：

classDiagram
    class Animal {+name : String}

1. 关系描述

   • 继承关系：<|--用于表示继承关系，比如Animal <|-- Dog，清晰说明 Dog 类继承自 Animal 类，继承了 Animal 类的相关特性与方法。

   • 关联关系：简单的关联关系用--表示，还能添加箭头方向与数字来细化关联程度，例如class A -- class B表示 A 和 B 类之间有某种关联。

   • 代码示例：

     classDiagram
         class Shape {shape}
         class Circle {+radius : double}
         Shape <|-- Circle
         class Drawer {drawer}
         Drawer -- Shape
     

三、Mermaid 实践应用

（一）项目流程梳理

在项目管理场景下，Mermaid 流程图能将项目从筹备、启动、执行到收尾的全过程可视化。以一个软件开发项目为例：

graph TD;
    project_init[项目筹备] --> project_start[项目启动];
    project_start --> requirements[需求收集];
    requirements --> design[架构设计];
    design --> coding{编码阶段};
    coding --> code_dev[代码开发] --> code_test[代码测试];
    coding --> bug_fix[漏洞修复];
    code_test --> integration[集成测试];
    integration --> deployment[部署上线];
    deployment --> project_close[项目收尾];

这份流程图让项目团队成员，包括开发人员、测试人员、项目经理等，一眼就能看清项目的关键环节以及可能的分支走向，提前规划资源、安排人力。

（二）系统交互呈现

对于一个电商系统，前端、后端、数据库以及第三方支付平台之间交互频繁，用时序图来展现最为合适：

sequenceDiagram
    participant FrontEnd
    participant BackEnd
    participant Database
    participant PaymentPlatform

    FrontEnd->>BackEnd: 用户下单请求
    activate BackEnd
    BackEnd->>Database: 查询库存
    Database-->>BackEnd: 返回库存信息
    BackEnd->>PaymentPlatform: 请求支付
    PaymentPlatform-->>BackEnd: 支付结果
    BackEnd-->>FrontEnd: 订单处理结果
    deactivate BackEnd

开发团队依据这个时序图，可以快速定位交互过程中的潜在问题，比如某个消息传递延迟或者没有响应，提升系统稳定性。

（三）学习计划安排

学生制定学习计划时，甘特图能科学规划课程学习、作业、考试等各项任务的时间分配：

gantt
    dateFormat YYYY-MM-DD
    title 大学计算机课程学习计划
    section 基础课程
        计算机基础 :a1, 2025-01-01, 7d
        C语言编程 :a2, after a1, 14d
    section 进阶课程
        数据结构 :a3, after a2, 21d
        算法分析 :a4, after a3, 14d
    section 考核
        期中考试 :a5, after a4, 3d
        期末考试 :a6, after a5, 3d

学习者借助甘特图，合理安排课余时间，把控学习进度，避免任务堆积。

（四）软件架构剖析

在分析一个企业级软件架构时，类图可用于展示不同类之间的继承、关联关系：

classDiagram
    class User {+name : String, +id : int}
    class Employee {+department : String}
    class Manager {+teamSize : int}
    User <|-- Employee
    Employee <|-- Manager
    class Task {+description : String}
    Employee -- Task

开发和维护团队看着类图，就能明晰类的层次结构，清楚哪些类复用了功能，哪些类负责具体业务逻辑关联，方便代码重构与功能扩展。

四、进阶技巧与拓展

1. 样式定制

   • Mermaid 允许一定程度的样式定制，虽然不像专业图形设计软件那么丰富，但足以区分图表元素。例如，在流程图中，可以给节点添加背景色，语法为style 节点名 fill:#颜色代码，A[节点A] ; style A fill:#FFE4B5 ，让节点 A 呈现出浅黄色背景。

2. 与其他工具集成

   • 与 GitBook、Hugo 等静态网站生成器集成，在生成网页文档时，自动把 Mermaid 代码渲染成精美的图表，扩大文档受众范围，提升可读性。同时，在一些代码托管平台如 GitHub，直接在 Markdown README 文件里使用 Mermaid 代码，能为开源项目的介绍、使用指南增色不少。

3. 复杂逻辑表达

   • 在流程图里，遇到多层嵌套的条件判断时，合理利用子图与不同流向箭头，搭配注释，即便非常复杂的业务流程也能清晰呈现。例如，涉及多个部门审批的流程，每个审批环节有不同的分支情况，通过细致划分子图来梳理。

4. 动态交互（部分支持场景）

   • 在一些支持 JavaScript 交互的网页环境里，结合 Mermaid 生成的图表，可以添加简单的点击事件、显示隐藏效果等动态交互，让图表从静态展示迈向动态探索，增强用户体验，挖掘图表深层次信息。