---
title: Mermaid 时序图写法入门
canonical: "https://mermaid.vloam.com/zh/docs/sequence/"
pubDate: 2026-09-13
author: Vloam
description: 用参与者、同步与异步箭头以及简短注释，画出谁在什么顺序下发消息；覆盖别名、Note、alt 分支与 loop 循环，并给出控制消息数量的写作建议。
---

时序图只回答一个问题：谁跟谁说话，顺序是什么？

时间从上往下推进。每个参与者有一条竖线。消息在左右之间传递。

## 开头怎么写

```mermaid
sequenceDiagram
  participant 用户
  participant API
  用户->>API: 请求数据
  API-->>用户: 返回结果
```

第一行必须是 `sequenceDiagram`。然后用 `participant` 或 `actor` 列出人或系统。

- `participant` — 系统或组件
- `actor` — 人（画法略有不同）

## 选对箭头

| 箭头 | 常见含义 |
| --- | --- |
| `->>` | 实线，多表示调用 |
| `-->>` | 虚线，多表示返回 |
| `->` | 实线，箭头较轻 |
| `-->` | 虚线，箭头较轻 |

常见写法：请求用 `->>`，响应用 `-->>`。

## 给参与者起短名

名字太长会挤版面。可以用别名：

```mermaid
sequenceDiagram
  participant FE as 前端
  participant BE as 后端
  FE->>BE: POST /login
  BE-->>FE: 200 OK
```

读者看到「前端」，语法里仍写 `FE`。

## 加注释

注释用来说明时机或规则，不必伪造一条消息：

```mermaid
sequenceDiagram
  participant 应用
  participant 数据库
  应用->>数据库: 查询
  Note right of 数据库: 缓存未命中
  数据库-->>应用: 行数据
```

注释放在相关参与者旁边。

## 表示分支或循环

分支用 `alt` / `else`，重复用 `loop`：

```mermaid
sequenceDiagram
  participant 客户端
  participant 服务端
  客户端->>服务端: Ping
  alt 正常
    服务端-->>客户端: OK
  else 故障
    服务端-->>客户端: Error
  end
```

这些块要短。`alt` 套 `alt` 会很快难读。

## 写作建议

- 参与者用真实角色名：`用户`、`编辑器`、`鉴权`。
- 一条消息只表达一个动作。
- 两边来回超过六次，就拆成两张图。