按时间描述系统交互

Mermaid 时序图在线编辑器

按消息发生顺序描述 API 请求、结账交互或服务调用。通过上方 Mermaid 时序图编辑器检查参与者、条件分支与响应，再导出用于评审的图表。

在线创建 Mermaid 时序图

示例将校验失败与成功写入数据库分开。可以粘贴自己的 sequenceDiagram 源码，或参考下方请求交互。

OnUML
Loading diagram preview...

说明谁在什么时候发送了什么消息

时序图把服务边界和失败响应放到同一条交互时间线上，适合 API 评审与故障说明，能够补充流程图没有展开的参与者职责。

人员与系统

用 actor 表示人员，用 participant 表示应用、服务或数据存储。

请求与响应路径

通过不同箭头样式和准确消息标签说明跨越边界的内容。

成功、失败与重复

用 alt 表示不同结果，opt 表示可选交互，loop 表示重复消息。

消息编号与补充说明

用 autonumber 编号，必要时用 note 解释超时或接口契约。

从头到尾说明一次请求

一张图围绕一次交互，同时包含会改变结果的失败路径。

  1. 01

    声明 sequenceDiagram，按希望展示的顺序声明参与者。

  2. 02

    从上到下添加消息，用 alt 区分成功和失败，每个条件块用 end 结束。

  3. 03

    分别检查两种结果，再导出图表或分享当前草稿给评审者。

消息与条件块的时序图语法

源码中的消息顺序决定展示顺序。箭头样式用于表达约定，不会验证网络调用的实际行为。

Mermaid 时序图语法参考 →

参与者、人员与别名

提前声明参与者可控制从左到右的顺序。别名允许保留简短源码 ID，同时显示清楚的职责名称。

sequenceDiagram
    actor Customer as 客户
    participant API as 订单服务
    Customer->>API: 创建订单

请求与响应箭头

->> 是带箭头的实线，-->> 是带箭头的虚线。将它们用于请求与响应是表达约定，不代表工具验证调用是否同步。

sequenceDiagram
    participant Client as 客户端
    participant API as 订单服务
    Client->>API: 查询订单
    API-->>Client: 返回订单列表

不同交互结果

alt 和 else 内只放两条路径不同的消息。需要拒绝无效输入时，把数据写入放在校验通过的分支。

sequenceDiagram
    participant Client as 客户端
    participant API as 订单服务
    participant DB as 数据库
    Client->>API: 创建订单
    alt 订单有效
        API->>DB: 保存订单
        API-->>Client: 返回确认结果
    else 订单无效
        API-->>Client: 返回校验错误
    end

循环与消息编号

loop 描述重复交互，autonumber 自动给消息编号。循环条件是展示文字，不是可以执行的控制流。

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant API as 任务服务
    loop 直到任务就绪
        Client->>API: 查询状态
        API-->>Client: 返回当前状态
    end

激活条与补充说明

用 activate 和 deactivate 标记参与者在一段交互中的活动，用 Note 在生命线旁补充说明。它们表达建模含义，不测量实际耗时。

sequenceDiagram
    participant Client as 客户端
    participant API as 订单服务
    Client->>API: 创建订单
    activate API
    Note right of API: 校验请求
    API-->>Client: 返回确认结果
    deactivate API

Mermaid 时序图示例

用户通过 Web 应用提交请求，API 先完成校验，再分别处理成功写入或校验失败的响应。

sequenceDiagram
    actor User as 用户
    participant Web as Web应用
    participant API as API服务
    participant DB as 数据库
    User->>Web: 提交请求
    Web->>API: 发送创建请求
    API->>API: 校验请求
    alt 请求有效
        API->>DB: 保存请求
        DB-->>API: 返回请求编号
        API-->>Web: 返回创建成功
        Web-->>User: 展示确认结果
    else 校验失败
        API-->>Web: 返回校验错误
        Web-->>User: 提示修改输入
    end
  • 数据库消息只在“请求有效”分支出现，校验失败不会进入写入路径。
  • 虚线响应把结果经 Web 应用返回给用户。
  • 尝试在成功写入后增加 opt 发送邮件块，保持失败路径不变。

常见问题

如何调整参与者的左右顺序？

在消息之前按目标顺序写 actor 和 participant 声明。不显式声明时，参与者按首次出现的顺序排列。

什么时候使用 actor？

需要人员样式图标时使用 actor，应用和服务通常用 participant。两者都会创建生命线。

alt、opt 和 loop 有什么区别？

alt 表示可带 else 的不同结果，opt 包住可选交互，loop 描述重复消息。每个块都需要匹配的 end。

如何添加激活条？

在收到消息后写 activate API，在返回响应后写 deactivate API，确保每次激活都有对应的结束。激活条表示你建模的活动，不代表测量出的响应时间。

为什么出现 end 相关语法错误？

先检查每个条件或循环块是否有匹配的 end。如果消息或标签需要出现 end 这个词，用引号、括号或方括号包住，不要裸写。

可以表示并行交互吗？

可以使用 par 块，并用 and 分隔并行分支。这是在描述交互，不代表工具测量了真实执行时间。

深入比较

比较 Mermaid 与 PlantUML 时序图

了解两种语法在参与者、消息、分支、循环和复杂交互维护方面的取舍。

阅读时序图对比指南 →