Mermaid 图表与数学公式

Mermaid 简介

Mermaid 是一个基于文本的图表绘制工具，让你用类似 Markdown 的简单语法描述图表，由渲染引擎自动生成 SVG 图形。GitHub 从 2022 年 2 月起原生支持 Mermaid，无需任何插件。

```mermaid
# 所有 Mermaid 图表都写在 mermaid 代码块内
graph TD
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作]
    B -->|否| D[跳过]
    C --> E[结束]
    D --> E
```

流程图（Flowchart）

流程图是 Mermaid 最常用的图表类型，用于展示算法逻辑、业务流程、决策树等。

基本流程图

```mermaid
flowchart TD
    A([开始]) --> B[/获取用户输入/]
    B --> C{输入是否合法?}
    C -- 合法 --> D[(保存到数据库)]
    C -- 非法 --> E[显示错误提示]
    E --> B
    D --> F([结束])
```

流程图方向

节点形状大全

连接线类型

完整流程图示例

```mermaid
flowchart LR
    subgraph 用户侧
        U([用户])
    end
    subgraph 服务端
        API[API 网关]
        Auth{认证通过?}
        DB[(数据库)]
        Cache[(Redis 缓存)]
    end

    U -->|HTTP 请求| API
    API --> Auth
    Auth -->|否| E[返回 401]
    Auth -->|是| Cache
    Cache -->|命中| U
    Cache -->|未命中| DB
    DB -->|查询结果| Cache
    DB -->|返回数据| U
```

时序图（Sequence Diagram）

时序图展示多个系统/角色之间的交互时间顺序，是 API 文档、系统设计文档的标配。

```mermaid
sequenceDiagram
    actor 用户
    participant 前端 as 前端 (React)
    participant 网关 as API 网关
    participant 服务 as 后端服务
    participant DB as 数据库

    用户 ->> 前端: 点击登录按钮
    前端 ->> 网关: POST /auth/login {email, password}
    网关 ->> 服务: 转发请求
    服务 ->> DB: SELECT * FROM users WHERE email=?
    DB -->> 服务: 返回用户记录
    服务 ->> 服务: 验证密码 bcrypt
    alt 验证通过
        服务 -->> 网关: {token, user}
        网关 -->> 前端: 200 OK {token}
        前端 -->> 用户: 跳转到首页
    else 验证失败
        服务 -->> 网关: 401 Unauthorized
        网关 -->> 前端: 401 错误
        前端 -->> 用户: 显示"密码错误"
    end
```

时序图关键语法

类图（Class Diagram）

类图用于展示面向对象设计中的类结构和关系，适合代码架构文档。

```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        #String species
        -bool isAlive
        +makeSound() String
        +eat(food: Food) void
        +getAge() int
    }

    class Dog {
        +String breed
        +fetch(item: Item) void
        +bark() void
    }

    class Cat {
        +bool isIndoor
        +purr() void
        +scratch() void
    }

    class ServiceDog {
        +String serviceType
        +assist(person: Person) void
    }

    Animal <|-- Dog : 继承
    Animal <|-- Cat : 继承
    Dog <|-- ServiceDog : 继承
    Dog "1" *-- "many" Toy : 组合
    Cat "1" o-- "0..1" Owner : 聚合
```

类图的关系类型

类成员可见性

ER 图（Entity Relationship Diagram）

实体关系图用于数据库设计，展示表结构和表间关系：

```mermaid
erDiagram
    USER {
        int id PK
        string email UK "唯一邮箱"
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total_amount
        string status
        datetime created_at
    }

    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }

    PRODUCT {
        int id PK
        string name
        decimal price
        int stock
    }

    USER ||--o{ ORDER : "下单"
    ORDER ||--|{ ORDER_ITEM : "包含"
    PRODUCT ||--o{ ORDER_ITEM : "属于"
```

ER 图基数符号

其他常用图表类型

甘特图（Gantt Chart）

```mermaid
gantt
    title 项目开发计划
    dateFormat YYYY-MM-DD
    section 设计阶段
        需求分析          :done,    des1, 2026-03-01, 2026-03-07
        UI 设计           :done,    des2, 2026-03-05, 2026-03-14
        数据库设计         :done,    des3, 2026-03-10, 2026-03-16
    section 开发阶段
        后端 API 开发      :active,  dev1, 2026-03-15, 20d
        前端开发           :         dev2, after dev1, 15d
        联调测试           :         dev3, after dev2, 7d
    section 上线阶段
        预发布测试         :crit,    rel1, after dev3, 3d
        正式上线           :crit,    rel2, after rel1, 1d
```

状态图（State Diagram）

```mermaid
stateDiagram-v2
    [*] --> 待支付
    待支付 --> 已支付 : 用户付款
    待支付 --> 已取消 : 超时取消
    已支付 --> 备货中 : 触发发货
    备货中 --> 已发货 : 发货完成
    已发货 --> 已签收 : 用户签收
    已签收 --> [*]
    已取消 --> [*]
    已发货 --> 退款中 : 申请退款
    退款中 --> 已退款 : 退款审核通过
    已退款 --> [*]
```

饼图

```mermaid
pie title 编程语言使用分布
    "JavaScript" : 35
    "Python"     : 28
    "Java"       : 15
    "TypeScript" : 12
    "Go"         : 6
    "其他"       : 4
```

数学公式（LaTeX / MathJax）

GitHub 从 2022 年起支持 LaTeX 数学公式，使用 MathJax 渲染（GitHub）或 KaTeX（Docusaurus/MkDocs 等）。

内联公式（行内公式）

用单个美元符号 $...$ 包裹（GitHub 支持）：

著名的质能方程 $E = mc^2$ 由爱因斯坦提出。

二次方程的解为 $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$。

黄金比例 $\varphi = \frac{1+\sqrt{5}}{2} \approx 1.618$。

独立公式块

用双美元符号 $$...$$ 创建独立居中的公式块：

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

$$
\int_{-\infty}^{+\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
\begin{pmatrix}
x \\
y
\end{pmatrix}
=
\begin{pmatrix}
ax + by \\
cx + dy
\end{pmatrix}
$$

常用 LaTeX 语法速查

LaTeX 支持情况

Mermaid 的局限性与替代方案

小结

• Mermaid：文字语法绘图，GitHub 2022 年起原生支持；代码放在 ```mermaid 代码块中
• 流程图：flowchart TD/LR，支持多种节点形状（矩形、菱形、圆柱体等）和连接线类型
• 时序图：sequenceDiagram，展示角色间交互；支持 alt、loop、opt 结构
• 类图：classDiagram，支持继承、组合、聚合等关系；成员用 +/-/# 表示可见性
• ER 图：erDiagram，支持 PK/FK/UK 约束和基数表示
• LaTeX 数学公式：内联用 $...$，块级用 $$...$$；GitHub 2022 年起支持
• 选择正确的工具：Mermaid 适合中等复杂度图表；过于复杂时改用专业绘图工具