如何用 Mermaid 画时序图

2026-03-04 · MermZen 教程

时序图（Sequence Diagram）描述多个参与者之间按时间顺序发生的消息交互。与流程图不同，时序图的核心问题是：谁在什么时候向谁发送了什么。适合展示 API 调用链路、用户与系统的交互、微服务通信等场景。

为什么用时序图？

时序图是展示交互流程的最佳选择：

• 展示多个参与者之间的消息交互 — 清晰呈现"谁对谁做了什么"
• 特别适合展示 API 调用链路 — 前端→后端→数据库→缓存的完整链路一目了然
• 清晰表达"谁在什么时候向谁发送了什么" — 时间轴从上到下，顺序直观

sequenceDiagram
    actor 用户 as User
    participant 前端 as Frontend
    participant API as API Server
    participant 数据库 as Database
    
    用户->>前端: 点击登录
    前端->>API: POST /api/login
    API->>数据库: SELECT * FROM users
    数据库-->>API: 用户数据
    API-->>前端: 200 OK + Token
    前端-->>用户: 跳转首页

声明图表与参与者

sequenceDiagram
    participant 用户
    participant 服务器
    participant 数据库

• sequenceDiagram 声明图表类型
• participant 名称 显式声明参与者，控制左右排列顺序
• 若不声明，在消息中使用的名称会自动创建参与者（按出现顺序排列）
• 使用 actor 名称 可以将参与者渲染为小人图标（适合表示真实用户）

为参与者设置别名，使代码简洁：

sequenceDiagram
    participant U as 用户
    participant S as 服务器
    U->>S: 发送请求

消息箭头类型

Mermaid 提供六种消息样式，覆盖请求、响应、异步等场景：

sequenceDiagram
    A->>B: 实线带开放箭头（同步请求）
    B-->>A: 虚线带开放箭头（同步响应）
    A->B: 实线无箭头
    A-->B: 虚线无箭头
    A-xB: 实线带叉（失败/丢弃）
    A-)B: 实线带异步箭头（非阻塞）
    A--)B: 虚线带异步箭头

箭头类型选择指南

选择正确的箭头类型可以让图表语义更清晰：

sequenceDiagram
    participant 客户端
    participant 服务器
    
    客户端->>服务器: HTTP请求 (同步)
    服务器-->>客户端: HTTP响应 (返回值)
    
    客户端-)服务器: WebSocket消息 (异步)
    服务器--)客户端: 推送通知 (异步响应)
    
    客户端-x服务器: 请求超时 (失败)

备注（Note）

在参与者旁边添加说明文字：

sequenceDiagram
    participant A
    participant B
    Note right of A: 这是 A 的备注
    Note over A,B: 横跨多个参与者的备注
    A->>B: 消息

最佳实践

参与者命名建议

• 使用 actor 表示真实用户（会渲染为小人图标）
• 使用 participant 命名系统组件（服务、数据库、缓存等）
• 使用 as 关键字设置简短别名，保持代码简洁

添加关键说明

使用 note 为关键步骤添加说明，帮助读者理解复杂逻辑：

sequenceDiagram
    participant A
    participant B
    Note right of A: 这是 A 的备注
    Note over A,B: 横跨多个参与者的备注
    A->>B: 消息

控制参与者数量

建议参与者不超过 5 个。过多的参与者会让图表变得难以阅读。如果系统复杂，考虑：

• 拆分为多个时序图
• 使用 box 将相关参与者分组
• 省略次要的中间步骤

sequenceDiagram
    actor 用户
    participant 前端
    participant API服务
    participant 缓存
    participant 数据库
    
    Note over 用户,数据库: 推荐不超过5个参与者
    
    用户->>前端: 发起请求
    前端->>API服务: API调用
    API服务->>缓存: 查询缓存
    缓存-->>API服务: 缓存命中
    API服务-->>前端: 返回结果
    前端-->>用户: 显示数据

与其他图表对比

选择建议：

• 需要展示谁对谁做了什么 → 时序图
• 需要展示条件分支和循环 → 流程图
• 需要展示完整业务流程 → 活动图

控制结构

循环（loop）

sequenceDiagram
    loop 每隔 30 秒
        客户端->>服务器: 心跳检测
        服务器-->>客户端: pong
    end

条件分支（alt / else）

sequenceDiagram
    客户端->>服务器: POST /login
    alt 验证通过
        服务器-->>客户端: 200 OK + Token
    else 密码错误
        服务器-->>客户端: 401 Unauthorized
    else 账号被锁定
        服务器-->>客户端: 403 Forbidden
    end

可选操作（opt）

sequenceDiagram
    服务器->>客户端: 返回数据
    opt 开启了通知
        服务器->>推送服务: 发送通知
    end

并行操作（par）

sequenceDiagram
    par 同时执行
        服务器->>邮件服务: 发送邮件
    and
        服务器->>短信服务: 发送短信
    end

完整示例：HTTP 登录接口调用链

sequenceDiagram
    actor 用户
    participant 浏览器
    participant API服务器
    participant Redis缓存
    participant MySQL

    用户->>浏览器: 填写账号密码并点击登录
    浏览器->>API服务器: POST /api/login {username, password}

    API服务器->>Redis缓存: GET login_fail:{username}
    Redis缓存-->>API服务器: 失败次数 (0)

    API服务器->>MySQL: SELECT * FROM users WHERE username=?
    MySQL-->>API服务器: 用户记录

    alt 密码验证通过
        API服务器->>API服务器: 生成 JWT Token (HS256)
        API服务器->>Redis缓存: SET session:{token} 7d
        API服务器-->>浏览器: 200 OK {token, user}
        浏览器->>浏览器: 存入 localStorage
        浏览器-->>用户: 跳转首页
    else 密码错误
        API服务器->>Redis缓存: INCR login_fail:{username}
        API服务器-->>浏览器: 401 {error: "密码错误"}
        浏览器-->>用户: 显示错误提示
    end

速查表

下一步

了解时序图后，继续学习 Mermaid 甘特图，用于展示项目任务与时间线安排。

如果您想在 MermZen 中尝试上述代码，可以点击 在线编辑器，然后将代码粘贴进去。