Как написать sequence-диаграмму mermaid
Sequence-диаграмма показывает, кто с кем говорит и в каком порядке. В mermaid она пишется примерно за то же время, что уходит на устный пересказ — поэтому это тип диаграммы, который дольше всех живёт в кодовой базе. Всё ниже готово к вставке в редактор.
Минимум
Объявите тип диаграммы, затем пишите по одной строке на сообщение. Участники создаются при первом упоминании, в порядке появления.
sequenceDiagram
User->>API: POST /orders
API->>DB: INSERT order
DB-->>API: order id
API-->>User: 201 CreatedОбъявляйте участников явно через participant User, если нужен конкретный порядок слева направо, а не порядок первого упоминания.
Типы стрелок
| Синтаксис | Значение |
|---|---|
A->>B: text | Запрос — сплошная линия, закрашенный наконечник |
A-->>B: text | Ответ — пунктирная линия, закрашенный наконечник |
A->B: text | Сплошная линия, открытый наконечник |
A-)B: text | Асинхронное сообщение — открытый наконечник, ответ не ожидается |
A-xB: text | Сообщение, которое падает или теряется |
Соглашение, которого стоит держаться: сплошная линия для вызова, пунктирная для ответа. Тогда читатель отличит запрос от ответа, даже не читая подписи.
Участники и псевдонимы
sequenceDiagram
participant U as Browser
participant A as API gateway
participant S as Order service
U->>A: GET /orders
A->>S: list(userId)
S-->>A: orders
A-->>U: 200 OKИспользуйте actor U as Browser вместо participant, чтобы нарисовать человечка — это того стоит для пользователя на левом краю сценария аутентификации.
Полосы активации
Полосы активации показывают, сколько времени участник занят. Отмечайте их явно через activate/deactivate, либо добавляйте + и - к стрелкам — это короче и сложнее рассинхронизировать.
sequenceDiagram
User->>+API: POST /pay
API->>+Bank: charge
Bank-->>-API: authorised
API-->>-User: receiptЦиклы, условия и параллельная работа
sequenceDiagram
User->>API: POST /import
loop every row
API->>DB: upsert row
end
alt all rows valid
API-->>User: 200 OK
else some failed
API-->>User: 422 with errors
end
par notify
API->>Email: send summary
and audit
API->>Log: write entry
endloop <label>…end— повторение.alt <label>…else <label>…end— взаимоисключающие ветви.opt <label>…end— ветвь, которая может просто не произойти.par <label>…and <label>…end— события, происходящие одновременно.critical/break— секция, которую нельзя прерывать, и досрочный выход.
Заметки
sequenceDiagram
User->>API: POST /login
Note right of API: Rate limited<br>5 per minute
API-->>User: token
Note over User,API: Token is valid for 30 daysNote over A,B охватывает двух участников и подходит для ограничения, которое относится к взаимодействию в целом, а не к одной из сторон.
Полный пример
sequenceDiagram
actor U as User
participant A as App
participant P as Provider
U->>+A: Click "Sign in"
A-->>-U: Redirect to provider
U->>+P: Authorise
P-->>-U: Redirect back with code
U->>+A: GET /callback?code=…
A->>+P: Exchange code for token
P-->>-A: access token
Note right of A: Session cookie set here
A-->>-U: Signed inОтредактируйте эту диаграмму
Вставьте её во вкладку кода и поменяйте строку — превью перерисуется на лету.
Частые вопросы
Как пронумеровать сообщения?
Поставьте autonumber строкой сразу после sequenceDiagram. Тогда каждое сообщение получит порядковый номер, и о диаграмме станет намного проще говорить в комментариях к ревью.
Может ли участник отправить сообщение самому себе?
Да — напишите одно и то же имя с обеих сторон: API->>API: retry. Mermaid нарисует петлю обратно на ту же линию жизни.
Как показать, что участник уничтожается?
Используйте destroy <name> перед сообщением, которое его завершает, или create participant <name>, чтобы он появился в середине диаграммы, а не в самом верху.
Можно ли редактировать sequence-диаграмму на визуальном холсте?
Визуальный холст редактирует flowchart-диаграммы. Sequence-диаграммы пишутся на вкладке кода, где они рендерятся вживую в превью — и это обычно быстрее, поскольку sequence-диаграмма — это, по сути, список строк.