Mermaid.js 时序图语法指南

什么是时序图？

一个时序图是一种关键的行为UML 图用于可视化不同系统实体之间在时间轴上的消息、函数调用和数据负载的时序流程。被公认为核心UML 图类型，它通过将系统组件沿X轴堆叠为垂直的生命线，并沿Y轴追踪消息交换来描绘运行时交互。这一蓝图对开发者调试分布式API握手、微服务编排路径或实时用户认证流程极为宝贵。

使用Mermaid.js，你可以使用直观的文本结构来编写复杂的时序过程。引擎会自动处理垂直间距，管理消息箭头对齐，并在画布上清晰绘制运行时激活块。

核心语法指南：元素与结构

要在Mermaid中设计出准确且易于扫描的UML时序图，你必须掌握参与者声明、消息箭头变体、显式生命线以及条件块结构。

1. 声明参与者和角色

你使用participant关键字来声明一个标准系统实体。如果该实体代表人类终端用户或外部操作员，请使用actor关键字在画布上渲染一个标准的棒状人物图标：

sequenceDiagram
    actor 客户端
    participant API as 网关路由器

专业提示：使用as关键字将长组件名称映射为紧凑的内部别名，使你的消息脚本简洁且易于阅读。

2. 格式化消息箭头

你使用的线条类型和箭头样式决定了系统参与者之间的通信风格：

• ->> **同步调用：** 实线带实心箭头。表示一个阻塞请求，会等待执行完成。
• --> **响应线：** 虚线带空心箭头。用于返回数据负载或确认令牌。
• -> **异步调用：** 实线带空心箭头。表示非阻塞的消息或事件广播。

sequenceDiagram
    App->>Server: 请求负载
    Server-->App: 200 OK 响应

3. 管理生命线激活条

要精确显示系统组件何时正在执行任务或占用线程内存，请使用activate 和 deactivate 命令。或者，您可以直接在消息目标后添加加号（+）或减号（-）符号作为快速的视觉快捷方式：

sequenceDiagram
    Client->>+Server: 处理数据
    %% 服务器现在在视觉上处于激活状态
    Server-->-Client: 返回结果

4. 结构化条件和替代方案（Alt、Opt、Loop）

为了处理分支运行时逻辑、令牌评估或重复的请求重试，请将您的消息脚本包裹在标准块片段中：

• alt / else — 评估条件路径（类似于 if/else 代码块）。
• opt — 定义一个仅在特定条件下执行的可选步骤。
• 循环 — 重复执行一个操作序列，直到满足某个条件为止。

sequenceDiagram
    循环 每30秒
        客户端->>服务器: 心跳探测
    结束

清晰序列时间线的最佳实践

• 保持生命线简洁： 避免在 X 轴上列出数十个微实体。如果一个过程与次要的辅助类交互，应将其抽象到高层系统边界之后，例如[认证工作器] 或 [缓存池].
• 明确标注状态码： 在编写响应返回时（-->），不要只写“返回数据”。用明确的 HTTP 状态码或事件类型标注路径（例如，"201 已创建（JWT 令牌）"），为工程师提供精确的上下文信息。
• 为复杂计算添加注释： 使用 Note over, Note left of，或 Note right of 指令来记录非可视化操作，例如内部加密步骤或数据库数据哈希。

现实世界中的 Mermaid.js 序列图示例

示例 1：安全的 OAuth2 令牌交换流程（激活与替代分支）

此功能蓝图模拟了一个安全的用户登录流程。它展示了如何使用 alt/else 分支组合人类参与者、明确的系统生命线以及复杂的验证路径。

sequenceDiagram
    actor User as 最终用户
    participant App as 移动应用客户端
    participant Auth as Auth0 身份提供者

    User->>+App: 点击“使用 OAuth 登录”
    App->>+Auth: 重定向并携带 client_id 和 scope
    Auth-->>User: 渲染登录界面
    User->>Auth: 提交凭据
    
    Auth->>Auth: 验证密码哈希
    
    alt 凭据有效
        Auth-->>App: 302 重定向并携带授权码
        App->>Auth: 用授权码换取访问令牌
        Auth-->>-App: 返回 JWT 令牌（IdToken）
        App-->>User: 渲染用户账户主页
    else 凭据无效
        Auth-->>App: 返回 401 未授权错误
        App-->>-User: 显示“用户名或密码错误”提示
    end

语法解析： 此时间线记录了多方握手过程。alt / else 容器清晰地展示了二元验证路径，确保错误状态与正常流程一同被完整记录。

示例 2：分布式订单库存结账（并行流程与注释）

此高级系统蓝图描绘了一个企业级电子商务结账流程。它利用并行块（par）来展示并发的 API 调度流程，并在拓扑结构中处理数据库锁定的注释。

sequenceDiagram
    participant Web as Web 前端
    participant Ord as 订单编排器
    participant Inv as 库存服务
    participant Pay as 支付网关

    Web->>+Ord: 提交结账请求
    Note over Ord: 验证商品库存可用性
    
    par 并发调用 API
        Ord->>+Inv: 锁定库存项目
        Inv-->-Ord: 库存已预留（库存锁定）
    and
        Ord->>+Pay: 授权信用卡扣款
        Pay-->-Ord: 扣款成功（交易结算）
    end
    
    opt 处理分配失败
        Note right of Ord: 若任一调用失败，则执行回滚流程
    end
    
    Ord-->-Web: 200 成功，结账确认

语法解析： 该par / and 容器指示引擎将并行执行操作组合在一起，记录并发的后端操作。Note over 和 Note right of 标签将技术运行时解释直接注入画布网格中，帮助团队理解数据锁定和回滚流程等后台事务，而不会使主消息箭头变得杂乱。