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

Диаграмма последовательности — главный инструмент аналитика интеграций: она показывает, кто кого вызывает, в каком порядке и что происходит при ошибке. В PlantUML её описание занимает несколько строк.

Минимальный пример

@startuml
actor Клиент
participant "Веб-приложение" as Web
participant "Order API" as API
database PostgreSQL as DB

Клиент -> Web: Оформить заказ
Web -> API: POST /orders
activate API
API -> DB: INSERT order
DB --> API: id
API --> Web: 201 Created
deactivate API
Web --> Клиент: Заказ оформлен
@enduml

Вставьте его в песочницу PlantUML или откройте шаблон: Файл → Примеры → Диаграмма последовательности.

Участники

actor, participant, boundary, control, entity, database, queue, collections — разные значки для людей, систем, хранилищ и очередей. Длинные названия — в кавычках с коротким псевдонимом as. Порядок объявления задаёт порядок колонок.

Сообщения

• -> — синхронный вызов, --> — ответ (пунктир).
• ->> — асинхронное сообщение (открытая стрелка), например публикация в Kafka.
• ->x — потерянное сообщение, A -> A — вызов самого себя.
• activate/deactivate — полоса активности участника.

Условия, циклы, группы

alt оплата прошла
  API -> DB: UPDATE status = PAID
else отказ банка
  API --> Web: 402 Payment Required
end
loop каждые 5 минут
  Worker -> API: GET /orders?status=NEW
end
opt клиент указал email
  API ->> Mail: Отправить чек
end

Ещё пригодятся par (параллельно), critical, break, разделители == Оплата ==, заметки note right of API: … и задержки ...5 минут....

Советы

• Подписывайте сообщения так, как они выглядят в API: метод и путь, имя топика, код ответа.
• Показывайте ошибки через alt — именно они чаще всего теряются в постановках.
• autonumber нумерует сообщения — удобно ссылаться на шаги в тексте.

Полный синтаксис — в документации по PlantUML.

Вопросы и ответы

Как показать асинхронный ответ через очередь? Добавьте участника queue Kafka и покажите публикацию API ->> Kafka: OrderPaid и чтение Kafka ->> Notifier: OrderPaid — так видно, что ответа в той же цепочке нет.

Можно ли разбить длинную диаграмму на страницы? Да, командой newpage — при экспорте каждая страница станет отдельным изображением. Чаще удобнее разделить сценарий на несколько диаграмм.

Как выделить шаги цветом? Группы group и box "Внешние системы" #LightBlue … end box вокруг участников делают схему нагляднее.