Mermaid时序图完全指南

Mermaid时序图完全指南

前言：时序图在技术文档中的价值

在系统设计、接口文档和故障排查中，时序图（Sequence Diagram）是描述对象间交互过程的最佳可视化工具。与Mermaid其他图表相比，时序图特别擅长展示时间维度上的消息传递和并发处理流程。

本文将深入剖析Mermaid时序图的完整语法体系，通过丰富的实例代码和即时渲染效果，带你全面掌握这一强大的文档工具。

一、时序图基础结构

1.1 最小化示例

代码实现：

sequenceDiagram Alice->>John: 你好，John！ John-->>Alice: 你好，Alice！

语法解析：

• sequenceDiagram：声明时序图开始
• participant：可选，显式定义参与者（会自动按出现顺序创建）
• ->>：实线箭头，表示同步消息
• -->>：虚线箭头，表示异步消息

1.2 完整参与者定义

代码实现：

sequenceDiagram participant A as 用户端 participant B as 服务器 participant C as 数据库 A->>B: HTTP请求 B->>C: SQL查询 C-->>B: 查询结果 B-->>A: JSON响应

语法解析：

• participant 别名 as 显示名称：定义参与者并指定显示名称
• 参与者默认按代码中出现顺序排列，也可用participant语句控制顺序

二、消息类型详解

2.1 六种基本消息箭头

代码实现：

sequenceDiagram participant A as 客户端 participant B as 服务端 Note over A,B: 消息类型演示 A->>B: 同步消息 (实线箭头) A-->>B: 异步消息 (虚线箭头) B->>+A: 激活开始 A-->>-B: 激活结束 A-xB: 失败消息 (带X箭头) A--)B: 虚线无箭头

语法对照表：

2.2 消息标签样式

代码实现：

sequenceDiagram participant C as 客户端 participant G as 网关 participant S as 服务 C->>G: 带**加粗**标签 G->>S: 带`代码`标签 S-->>G: 带<br>换行标签 G-->>C: 普通标签

语法要点：

• 支持Markdown格式：**加粗**、*斜体*、`代码`
• 支持HTML标签：<br>换行、<b>加粗等
• 标签过长会自动换行

三、控制流程结构

3.1 条件分支 (alt/else)

代码实现：

sequenceDiagram participant U as 用户 participant S as 系统 U->>S: 登录请求(用户名,密码) alt 验证成功 S-->>U: 返回token U->>S: 获取用户信息 S-->>U: 用户数据 else 验证失败 S-->>U: 错误：密码错误 else 用户不存在 S-->>U: 错误：用户未注册 end

3.2 可选分支 (opt)

代码实现：

sequenceDiagram participant U as 用户 participant A as 认证服务 participant L as 日志服务 U->>A: 登录请求 opt 记录登录日志 A->>L: 记录登录事件 L-->>A: 日志记录成功 end A-->>U: 登录响应

3.3 循环结构 (loop)

代码实现：

sequenceDiagram participant C as 客户端 participant S as 服务器 C->>S: 请求商品列表 loop 每页处理 S->>S: 查询数据库 S-->>C: 返回一页数据 C->>C: 渲染页面元素 end S-->>C: 所有数据完成

3.4 并行处理 (par)

代码实现：

sequenceDiagram participant C as 客户端 participant AS as 认证服务 participant PS as 个人资料服务 participant NS as 通知服务 C->>AS: 用户登录 par 并行处理 AS->>PS: 获取用户资料 PS-->>AS: 返回资料 and AS->>NS: 发送登录通知 NS-->>AS: 通知已发送 end AS-->>C: 登录完成

3.5 关键区域 (critical)

代码实现：

sequenceDiagram participant A as 应用 participant D as 数据库 participant L as 锁服务 A->>D: 开始事务 critical 数据一致性区域 A->>L: 获取排他锁 L-->>A: 锁已分配 A->>D: 更新关键数据 A->>L: 释放锁 option 锁已被占用 A->>A: 等待重试 end A->>D: 提交事务

四、注释和标注系统

4.1 位置注释

代码实现：

sequenceDiagram participant C as 客户端 participant M as 中间件 participant S as 服务端 Note left of C: 用户发起请求 Note right of S: 服务端处理逻辑 C->>M: 请求数据 Note over C,M: 网络传输过程 M->>S: 转发请求 Note over S: 内部处理<br>耗时操作 S-->>M: 返回结果 M-->>C: 响应客户端

注意：注释最多只能跨2各对象

4.2 跨参与者注释

代码实现：

sequenceDiagram participant A as 应用A participant B as 应用B participant C as 应用C Note over A,B: 第一阶段交互 A->>B: 消息1 B-->>A: 响应1 Note over B,C: 第二阶段交互 B->>C: 消息2 C-->>B: 响应2 Note over A,B,C: 整体流程完成

4.3 激活区间

代码实现：

sequenceDiagram participant U as 用户 participant C as 控制器 participant S as 服务层 participant D as 数据层 U->>+C: 请求处理 C->>+S: 业务调用 S->>+D: 数据查询 D-->>-S: 返回数据 S-->>-C: 业务结果 C-->>-U: 最终响应 Note right of U: 激活区间清晰展示<br>调用深度

五、高级特性应用

5.1 自动编号

代码实现：

sequenceDiagram autonumber participant U as 用户 participant A as 认证服务 participant D as 数据库 U->>A: 1. 登录请求 A->>D: 2. 查询用户 D-->>A: 3. 返回用户数据 A->>A: 4. 验证密码 A-->>U: 5. 登录结果

5.2 背景色和区域分组

代码实现：

sequenceDiagram box rgb(240, 248, 255) 客户端 participant W as Web端 participant M as 移动端 end box rgb(220, 255, 220) 服务端 participant G as 网关 participant S as 业务服务 participant DB as 数据库 end W->>G: 请求1 M->>G: 请求2 G->>S: 转发请求 S->>DB: 数据操作 DB-->>S: 返回数据 S-->>G: 业务响应 G-->>W: 响应1 G-->>M: 响应2

5.3 自定义样式

代码实现：

sequenceDiagram participant A as 用户 participant B as 系统 Note over A: 这是用户角色 Note over B: 这是系统角色 A->>B: 重要请求 B-->>A: 成功响应 rect rgb(200, 150, 255) A->>B: 特殊处理请求 B-->>A: 特殊响应 end rect rgb(100, 200, 100) A->>B: 最后请求 B-->>A: 最终响应 end

5.4 循环中的中断

代码实现：

sequenceDiagram participant C as 客户端 participant S as 服务器 C->>S: 开始批量处理 loop 处理每个项目 S->>S: 处理当前项目 alt 处理成功 S-->>C: 进度更新 else 发生错误 S-->>C: 错误报告 break 停止处理 end end S-->>C: 处理完成

六、实际应用案例

6.1 用户登录完整流程

代码实现：

sequenceDiagram autonumber participant U as 用户 participant W as Web前端 participant G as API网关 participant A as 认证服务 participant UD as 用户服务 participant D as 数据库 participant R as Redis缓存 U->>W: 1. 输入账号密码 W->>G: 2. POST /api/login G->>A: 3. 验证请求 alt 验证通过 A->>D: 4. 查询用户信息 D-->>A: 5. 返回用户数据 A->>R: 6. 缓存Session R-->>A: 7. 缓存成功 A-->>G: 8. 生成Token G-->>W: 9. 返回Token W->>W: 10. 存储Token到LocalStorage par 并行操作 W->>UD: 11. 获取用户详情 UD-->>W: 12. 返回用户信息 and W->>W: 13. 跳转到首页 end W-->>U: 14. 显示登录成功 else 验证失败 A-->>G: 15. 返回错误码 G-->>W: 16. 转发错误 W-->>U: 17. 显示错误提示 end

6.2 电商下单支付流程

代码实现：

sequenceDiagram box LightBlue 用户端 participant U as 用户 participant APP as 购物APP end box LightGreen 业务服务 participant OS as 订单服务 participant PS as 支付服务 participant IS as 库存服务 participant LS as 物流服务 end box SandyBrown 第三方 participant PG as 支付网关 participant BANK as 银行系统 end U->>APP: 1. 提交订单 APP->>OS: 2. 创建订单 critical 订单创建关键区 OS->>IS: 3. 锁定库存 IS-->>OS: 4. 库存锁定成功 OS->>OS: 5. 生成订单号 option 库存不足 OS-->>APP: 库存不足错误 APP-->>U: 下单失败 end OS-->>APP: 6. 订单创建成功 APP->>U: 7. 跳转支付页面 U->>APP: 8. 选择支付方式 APP->>PS: 9. 发起支付 par 支付处理 PS->>PG: 10. 调用支付接口 PG->>BANK: 11. 银行扣款 BANK-->>PG: 12. 扣款成功 PG-->>PS: 13. 支付成功 PS->>OS: 14. 更新订单状态 OS->>LS: 15. 创建物流单 LS-->>OS: 16. 物流单创建完成 PS->>IS: 17. 扣减库存 IS-->>PS: 18. 库存扣减完成 end PS-->>APP: 19. 支付成功通知 APP-->>U: 20. 显示支付成功

七、样式自定义和主题

7.1 基础样式定制

代码实现：

%%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#1a365d', 'primaryTextColor': '#fff', 'primaryBorderColor': '#2d3748', 'lineColor': '#4fd1c7', 'secondaryColor': '#2d3748', 'tertiaryColor': '#edf2f7', 'noteBkgColor': '#fed7d7', 'noteTextColor': '#742a2a', 'actorBkg': '#3182ce', 'actorBorder': '#2c5282', 'actorTextColor': '#fff', 'actorLineColor': '#2d3748', 'signalColor': '#e53e3e', 'signalTextColor': '#fff' } }}%% sequenceDiagram participant 客户端 participant 服务器 participant 数据库 客户端->>服务器: 重要请求 Note over 服务器: 处理请求 服务器->>数据库: 查询操作 数据库-->>服务器: 返回数据 服务器-->>客户端: 响应结果

7.2 响应式设计

代码实现：

sequenceDiagram participant A as 移动客户端 participant B as 响应式服务端 participant C as 数据库 A->>B: 请求(带设备信息) B->>B: 根据设备适配逻辑 B->>C: 查询优化数据 C-->>B: 返回适配数据 B-->>A: 响应(适配格式) Note right of B: 根据User-Agent<br>返回不同数据格式

八、常见问题和解决方案

8.1 语法错误排查表

8.2 最佳实践建议

1. 命名规范

sequenceDiagram participant FE as 前端服务 participant BE as 后端服务 participant DB as 数据库

2. 结构清晰

sequenceDiagram autonumber Note over A,B: 第一阶段 A->>B: 步骤1 Note over B,C: 第二阶段 B->>C: 步骤2

3. 适度复杂度
   • 单个时序图建议不超过15个参与者
   • 消息数量控制在20条以内
   • 嵌套层次不超过3层

九、与其他工具集成

9.1 与文档工具结合

# API接口文档 ## 用户登录接口 **接口描述**: 用户通过账号密码登录系统 **调用时序**: ```mermaid sequenceDiagram participant C as 客户端 participant S as 认证服务 C->>S: POST /auth/login S-->>C: {token: "xxx", expires: 3600}

请求参数:

### 9.2 在代码注释中使用 ```javascript /** * 处理用户下单流程 * * 时序图: * ```mermaid * sequenceDiagram * participant U as 用户 * participant O as 订单服务 * participant P as 支付服务 * * U->>O: 提交订单 * O->>P: 创建支付 * P-->>O: 支付信息 * O-->>U: 订单确认 * ``` */ async function createOrder(userId, productId) { // 实现代码 }

总结

Mermaid时序图以其简洁的语法、强大的表现力和优秀的集成性，成为技术文档中不可或缺的工具。通过本文的详细讲解和丰富示例，你应该已经掌握了：

✅基础语法：参与者、消息、注释的创建
✅控制结构：条件、循环、并行的实现
✅高级特性：样式定制、主题配置、自动编号
✅实践应用：结合真实业务场景的复杂案例
✅最佳实践：保持图表清晰可维护的方法

在实际工作中，建议先从简单的交互流程开始，逐步增加复杂度。记住：清晰的时序图胜过千言万语，它能帮助团队理解系统、排查问题、优化设计。

现在就开始在你的项目文档中使用Mermaid时序图吧！

扩展学习：

• Mermaid官方文档
• 在线实时编辑器
• GitHub示例仓库