Руководство по синтаксису диаграмм последовательности Mermaid.js

Что такое диаграмма последовательности?

A Диаграмма последовательности — это важный поведенческий диаграмма UML предназначен для визуализации хронологического потока сообщений, вызовов функций и данных между различными системными сущностями вдоль линейного временного отрезка. Признан как основной тип диаграммы UML, она отображает взаимодействия во время выполнения, размещая компоненты системы вдоль оси X как вертикальные линии жизни, а отслеживая обмен сообщениями вдоль оси Y. Этот чертеж бесценен для разработчиков, отлаживающих распределённые API-рукопожатия, пути оркестрации микросервисов или потоки аутентификации пользователей в реальном времени.

С помощью Mermaid.js, вы можете описывать сложные временные процессы с помощью интуитивной текстовой структуры. Движок автоматически управляет вертикальными интервалами, управляет выравниванием стрелок сообщений и чисто рисует блоки активности во время выполнения на вашем холсте.

Основное руководство по синтаксису: элементы и конструкции

Чтобы создать точную, легко читаемую диаграмму последовательности UML в Mermaid, необходимо освоить объявления участников, варианты стрелок сообщений, явные линии жизни и структуры условных блоков.

1. Объявление участников и акторов

Вы объявляете стандартную системную сущность с помощью ключевого слова participant . Если сущность представляет конечного пользователя или внешнего оператора, используйте ключевое слово actor , чтобы отобразить стандартную иконку человечка на холсте:

sequenceDiagram
    actor Client
    participant API as Шлюз-маршрутизатор

Совет профессионала: Используйте ключевое слово as , чтобы сопоставить длинные имена компонентов с компактными внутренними псевдонимами, сохраняя ваши скрипты сообщений краткими и читаемыми.

2. Форматирование стрелок сообщений

Тип линии и стрелки определяет стиль коммуникации между участниками вашей системы:

• ->> **Синхронный вызов:** Сплошная линия с закрашенным концом стрелки. Представляет блокирующий запрос, ожидающий завершения выполнения.
• --> **Линия ответа:** Штриховая линия с открытым концом стрелки. Используется для возврата данных или токенов подтверждения.
• -> **Асинхронный вызов:** Сплошная линия с открытым концом стрелки. Указывает на неблокирующее сообщение или широковещательную передачу события.

sequenceDiagram
    Приложение->>Сервер: Запрос данных
    Сервер-->Приложение: Ответ 200 OK

3. Управление полосами активности жизненного цикла

Чтобы точно показать, когда компонент системы активно выполняет задачу или использует память потока, используйте командыactivate и deactivate команды. Альтернативно, вы можете добавить плюс (+) или минус (-) знак непосредственно к целям сообщений в качестве быстрого визуального способа:

sequenceDiagram
    Клиент->>+Сервер: Обработать данные
    %% Сервер теперь визуально активен
    Сервер-->-Клиент: Вернуть результаты

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 Пользователь как Конечный пользователь
    участник Приложение как Клиент мобильного приложения
    участник Аутентификация как поставщик идентификации Auth0

    Пользователь->>+Приложение: Нажать «Войти с помощью OAuth»
    Приложение->>+Аутентификация: Перенаправление с client_id и scope
    Аутентификация-->>Пользователь: Отобразить интерфейс входа
    Пользователь->>Аутентификация: Отправить учетные данные
    
    Аутентификация->>Аутентификация: Проверить хэш пароля
    
    alt Учетные данные верны
        Аутентификация-->>Приложение: 302 Перенаправление с кодом аутентификации
        Приложение->>Аутентификация: Обмен кода на токен доступа
        Аутентификация-->>-Приложение: Вернуть JWT-токен (IdToken)
        Приложение-->>Пользователь: Отобразить домашнюю страницу учетной записи пользователя
    else Неверные учетные данные
        Аутентификация-->>Приложение: Вернуть ошибку 401 Неавторизовано
        Приложение-->>-Пользователь: Показать предупреждение «Неверное имя пользователя/пароль»
    end

Разбор синтаксиса: Этот хронологический ряд отслеживает многосторонний обмен. Контейнер alt / else контейнер четко отображает двоичные пути проверки, обеспечивая полную документацию состояний ошибок вместе с основным путем выполнения.

Пример 2: Распределенная проверка заказа инвентаря (параллельные процессы и заметки)

Этот продвинутый чертеж системы отображает путь проверки заказа в корпоративной электронной коммерции. Он использует параллельные блоки (par) для отображения параллельных вызовов API и обработки заметок о блокировке базы данных на всем протяжении топологии.

sequenceDiagram
    участник Веб как Веб-интерфейс
    участник Заказ как Оркестратор заказов
    участник Инвентарь как Сервис инвентаря
    участник Оплата как Шлюз оплаты

    Веб->>+Заказ: Отправить запрос на оформление заказа
    Примечание над Заказом: Проверить наличие товара на складе
    
    par Отправка параллельных вызовов API
        Заказ->>+Инвентарь: Заблокировать товары на складе
        Инвентарь-->-Заказ: Товары зарезервированы (склад заблокирован)
    и
        Заказ->>+Оплата: Авторизовать списание с кредитной карты
        Оплата-->-Заказ: Операция прошла успешно (списание завершено)
    конец
    
    опт Процесс распределения не удался
        Примечание справа от Заказа: Выполнить откатную сагу, если какой-либо вызов завершится неудачно
    конец
    
    Заказ-->-Веб: 200 Успешно оформлен заказ подтвержден

Разбор синтаксиса: Контейнер par / and контейнер указывает движку объединять параллельные выполнения, документируя одновременные операции на бэкенде. Теги Примечание над и Примечание справа от вставляют технические пояснения во время выполнения непосредственно в сетку холста, помогая командам понять фоновые транзакции, такие как блокировка данных и откатные саги, не загромождая основные стрелки сообщений.