Диаграммы последовательности Mermaid

Диаграммы последовательности (sequence diagrams) описывают взаимодействие между компонентами, сервисами или пользователями в хронологическом порядке. Они незаменимы при документировании API, протоколов аутентификации, микросервисных взаимодействий и пользовательских сценариев.

Базовый синтаксис

sequenceDiagram
    participant Browser
    participant API
    participant DB

    Browser->>API: POST /auth/login
    API->>DB: SELECT user WHERE email=?
    DB-->>API: user record
    API-->>Browser: 200 OK { token }

Участники (Participants)

По умолчанию участники отображаются в порядке первого упоминания. Для явного задания порядка и алиасов:

sequenceDiagram
    participant U as Пользователь
    participant F as Фронтенд
    participant B as Бэкенд
    participant D as База данных

    U->>F: Открывает страницу
    F->>B: GET /api/tasks
    B->>D: SELECT * FROM tasks
    D-->>B: tasks[]
    B-->>F: 200 { tasks }
    F-->>U: Отображает список

Актёры (actor)

Используйте actor вместо participant для отображения людей в виде человечка:

sequenceDiagram
    actor User as 👤 Пользователь
    participant App as Приложение
    participant Server

    User->>App: Нажимает "Создать задачу"
    App->>Server: POST /api/tasks
    Server-->>App: 201 Created
    App-->>User: Задача добавлена

Типы сообщений

sequenceDiagram
    A->>B: Синхронный запрос
    B-->>A: Ответ
    A-)B: Async уведомление
    B-xA: Потеря сообщения

Активации

Активации показывают, когда участник занят обработкой:

sequenceDiagram
    Client->>+Server: Запрос
    Server->>+DB: Запрос к БД
    DB-->>-Server: Данные
    Server-->>-Client: Ответ

+ активирует участника, - деактивирует.

Заметки (Notes)

sequenceDiagram
    Alice->>Bob: Привет!
    Note right of Bob: Bob думает...
    Bob-->>Alice: Привет!
    Note over Alice,Bob: Они общаются

Позиции: right of, left of, over (один или несколько участников через запятую).

Условные блоки (alt/opt/par)

alt — условные ветки

sequenceDiagram
    Client->>Server: Запрос с токеном
    alt Токен валидный
        Server-->>Client: 200 OK
    else Токен истёк
        Server-->>Client: 401 Unauthorized
    else Токен отсутствует
        Server-->>Client: 403 Forbidden
    end

opt — необязательный блок

sequenceDiagram
    User->>App: Сохранить настройки
    App->>Server: PATCH /settings
    opt Включены уведомления
        Server->>Email: Отправить подтверждение
    end
    Server-->>App: 200 OK

par — параллельные операции

sequenceDiagram
    Server->>Server: Получен запрос

    par Параллельная обработка
        Server->>Cache: Инвалидировать кэш
    and
        Server->>DB: Обновить данные
    and
        Server->>Analytics: Записать событие
    end

    Server-->>Client: Ответ

Циклы

sequenceDiagram
    Client->>Server: Начать polling

    loop Каждые 5 секунд
        Client->>Server: GET /status
        Server-->>Client: { status: "processing" }
    end

    Server-->>Client: { status: "done" }

Критические секции (break/critical)

sequenceDiagram
    Service->>DB: Начать транзакцию

    critical Транзакция
        DB->>DB: Обновить запись A
        DB->>DB: Обновить запись B
    option Ошибка
        DB->>DB: Откат транзакции
    end

    DB-->>Service: Результат

Нумерация сообщений

sequenceDiagram
    autonumber
    Client->>Server: Запрос
    Server->>DB: Запрос
    DB-->>Server: Данные
    Server-->>Client: Ответ

Пример: OAuth 2.0 авторизация

sequenceDiagram
    actor User as 👤 Пользователь
    participant App as Приложение
    participant Auth as OAuth Provider
    participant API as Resource API

    User->>App: Войти через GitHub
    App->>Auth: Redirect /oauth/authorize
    Auth->>User: Страница авторизации
    User->>Auth: Подтверждает доступ
    Auth-->>App: code=abc123
    App->>Auth: POST /oauth/token {code}
    Auth-->>App: access_token, refresh_token
    App->>API: GET /user {Bearer token}
    API-->>App: user data
    App-->>User: Вошли как @username