跳转至

Mermaid 时序图与图类型速查

本节：mermaid 完整图类型速查 + 实际示例 配合：data/sequence-diagrams.md 已用 mermaid 画了 22+ 时序图 不重画：本节专注语法速查而非业务图

为什么用 mermaid？

  • ✅ 零依赖——直接写在 markdown 里，mkdocs-material 自动渲染
  • ✅ 版本控制——图随文档 commit，不会过时
  • ✅ 支持 7+ 图类型——比 vis.js / draw.io 更全
  • ✅ 可 fork 复用——复制代码块改字段即可

1. Sequence Diagram（时序图）⭐ 最常用

sequenceDiagram
    actor U as 用户
    participant R as REPL
    participant Q as QueryEngine
    participant C as Claude API

    U->>R: 输入 prompt
    R->>Q: 提交 messages
    Q->>C: POST /v1/messages
    C-->>Q: 流式 SSE
    Q-->>R: 增量 token
    R-->>U: 渲染文字
    U->>R: 发送 /clear
    R->>Q: reset state
    Q-->>R: ok

关键语法： - actor X = 人形 actor - participant X = 矩形 participant - ->> 实线箭头（同步） - -->> 虚线箭头（异步/返回） - --X 叉（失败） - Note over X: 文字 = 注释框 - loop ... end / alt ... else ... end = 控制流

2. Flowchart（流程图）

flowchart TD
    A[用户输入] --> B{权限检查}
    B -->|allow| C[执行工具]
    B -->|deny| D[报错]
    B -->|ask| E[询问用户]
    E -->|允许| C
    E -->|拒绝| D
    C --> F[返回结果]
    D --> G[错误日志]
    F --> H[渲染输出]

关键语法： - TD / LR = 方向（top-down / left-right） - [] = 矩形 / () = 圆角 / {} = 菱形 / ((())) = 圆 - --> 实线 / -.-> 虚线 / ==> 粗线 - |label| = 边标签

3. Class Diagram（类图）

classDiagram
    class Tool {
        +string name
        +call(input) Output
        +checkPermissions(input) Permission
    }
    class BashTool {
        -regex dangerousPatterns
        +matchBashSecurity(cmd) Severity
    }
    class FileReadTool {
        +readFile(path) string
    }
    Tool <|-- BashTool
    Tool <|-- FileReadTool

关键语法： - + public / - private / # protected - <|-- 继承 / *-- 组合 / o-- 聚合 - ~Function() 抽象方法 - <<interface>> 接口

4. State Diagram（状态机）

stateDiagram-v2
    [*] --> idle
    idle --> connecting: open
    connecting --> connected: ready
    connecting --> error: timeout
    connected --> disconnected: close
    connected --> reconnecting: error
    reconnecting --> connected: ok
    error --> [*]
    disconnected --> [*]

关键语法： - [*] = 起始/终止 - state 名称 { ... } = 复合状态 - state 名称 <<choice>> = 选择状态 - --> transition 标签

5. ER Diagram（实体关系）

erDiagram
    USER ||--o{ SESSION : creates
    USER ||--o{ MESSAGE : writes
    SESSION ||--|{ MESSAGE : contains
    SESSION ||--o{ TOOL_CALL : invokes
    TOOL_CALL }o--|| TOOL : uses

    USER {
        string id PK
        string email
        timestamp created_at
    }
    SESSION {
        string id PK
        string user_id FK
        timestamp started_at
    }
    MESSAGE {
        string id PK
        string session_id FK
        text content
        string role
    }

关键语法： - ||--o{ 一对多 / ||--|| 一对一 / }o--o{ 多对多 - PK/FK/UK 主键/外键/唯一键 - 块内定义字段

6. Gantt Chart（甘特图）

gantt
    title Claude Code 学习手册项目
    dateFormat YYYY-MM-DD
    section A 板块
    A1 源码拆解 :a1, 2026-06-04, 5d
    A2-A10 整体 :a2, after a1, 3d
    section B 板块
    B1-B3 配置 :b1, after a2, 2d
    section 部署
    D1 部署 :d1, after b1, 1d

7. Pie（饼图）

pie title Claude Code 源码类型分布
    "业务逻辑" : 35
    "工具实现" : 25
    "UI 组件" : 20
    "类型定义" : 10
    "测试代码" : 5
    "其他" : 5

8. Git Graph（git 分支图）

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit

9. Flow（业务流程 / 旧式）

flowchart 已包含 flow 全部功能，推荐用 flowchart。

配置（在 mkdocs.yml）

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

本仓库已配（mkdocs.yml line 88-92），无需额外配置。

Dark Mode 配色

本仓库在 learn_doc/assets/css/mermaid-dark.css 定义了：

[data-md-color-scheme="slate"] .mermaid svg {
  background: #1f1f23 !important;
}
[data-md-color-scheme="default"] .mermaid svg {
  background: #fafafa !important;
}

效果：浅色 / 深色模式分别用对应色板。

推荐

  • 业务时序用 sequenceDiagram
  • 架构 / 流程用 flowchart TD（垂直更省空间）
  • 状态机用 stateDiagram-v2
  • 类层级用 classDiagram
  • 数据模型用 erDiagram

关联

官方文档