Sequence-диаграммы для аналитика: кто кого зовёт и в каком порядке

Однажды я описал интеграцию с платёжным провайдером прозой: «бэкенд создаёт платёж, провайдер уводит клиента на свою страницу, клиент платит, провайдер дёргает нас вебхуком, мы проверяем подпись и обновляем заказ». На ревью разработчик и тестировщик хором спросили разное. Разработчик: «А кто первым ходит в банк — мы или провайдер?» Тестировщик: «А мы ждём ответа синхронно или он прилетает вебхуком потом?» Я понял, что в тексте порядок вызовов читается криво: фразы идут одна за другой, но кто кого зовёт и где ответ, а где новое событие — не видно. Перерисовал ту же интеграцию sequence-диаграммой за двадцать минут, и оба вопроса отпали сами. С тех пор любой сценарий «несколько систем общаются по шагам» я рисую, а не описываю абзацем.

Sequence-диаграмма ровно для этого и придумана: она навязывает вам ось времени. Вы физически не можете нарисовать стрелку, не ответив на вопрос «кто отправитель, кто получатель и что это — вызов или ответ». В прозе же легко написать «системы синхронизируются» и не заметить, что вы не сказали, в какую сторону идёт первый запрос.

Что такое sequence-диаграмма

Sequence-диаграмма — одна из диаграмм UML, и отвечает она на узкий, но частый вопрос: как участники сценария обмениваются сообщениями во времени. Не «какие у системы части» и не «какие у заказа статусы», а именно «кто кого зовёт, в каком порядке и что приходит в ответ».

Главная ось — время, и оно идёт сверху вниз. Чем ниже сообщение на диаграмме, тем позже оно происходит. Это первое, что нужно усвоить: горизонталь — это участники, вертикаль — это время. Поэтому sequence читается не как блок-схема (где стрелки ведут «куда угодно»), а как партитура: сверху вниз, шаг за шагом.

Из чего состоит диаграмма

Участники и линии жизни (lifelines). Каждый участник сценария — клиент, наш бэкенд, внешний сервис, база — это столбец сверху, от которого вниз тянется вертикальная пунктирная линия. Эта линия и есть lifeline — «жизнь» участника на протяжении сценария. Участником может быть человек, система, сервис, компонент — всё, что отправляет или получает сообщения.

Сообщения. Это горизонтальные стрелки между линиями жизни. Важно различать их тип, потому что от этого зависит смысл:

• Синхронный вызов — сплошная линия с закрашенной стрелкой (в mermaid это ->>). Означает «я зову тебя и жду, пока ты ответишь». Отправитель стоит и блокируется до ответа.
• Ответ (return) — пунктирная стрелка обратно (-->>). Это не новый вызов, а возврат результата на предыдущий синхронный запрос. Пунктир — визуальный маркер «это ответ, а не инициатива».
• Асинхронное сообщение — стрелка с открытым (незакрашенным) наконечником. Означает «я отправил и пошёл дальше, ответа здесь не жду». Так рисуют события, сообщения в очередь, вебхуки — всё, что про асинхронную интеграцию.

Активация (activation). Узкий вертикальный прямоугольник поверх линии жизни — он показывает, что участник в этот момент «занят», обрабатывает вызов. Активация начинается, когда участник получил сообщение, и кончается, когда он вернул ответ. На практике аналитику не обязательно вырисовывать активации вручную — многие инструменты рисуют их сами; важнее правильно расставить сообщения.

Фрагменты: alt, opt, loop, par

Простой сценарий — это прямая последовательность сообщений сверху вниз. Но в жизни почти всегда есть условия: «если оплата прошла — одно, если отказ — другое». Для этого в sequence есть фрагменты — рамки, которые оборачивают группу сообщений и помечены в левом верхнем углу типом.

• alt (alternative) — ветвление «или-или». Рамка делится на части горизонтальной чертой, в каждой части — условие в квадратных скобках (например, «оплата успешна» / «отказ»). Выполняется ровно одна ветка. Это аналог if-else.
• opt (optional) — опциональный блок: выполнится, только если условие истинно, иначе пропускается. Аналог if без else.
• loop — цикл: блок повторяется, пока выполняется условие (например, «для каждой позиции заказа» или «пока статус = pending»).
• par (parallel) — параллельность: два или больше блоков выполняются одновременно, порядок между ними не важен.

Когда брать sequence, а когда BPMN или состояния

Это вопрос, на котором путаются чаще всего, поэтому разберём по сути, а не по списку. Три нотации отвечают на три разных вопроса, и выбор идёт от вопроса, а не от привычки.

BPMN — про процесс и роли. Если вы описываете, как заявка проходит через отделы, где менеджер принимает решение, где процесс ждёт оплаты, кто за какой шаг отвечает, — это бизнес-процесс, и его место в BPMN с дорожками под роли. BPMN отвечает на «кто что делает в каком порядке». Подробнее — в записи какую нотацию когда использовать.

Sequence — про обмен сообщениями между системами во времени. Как только речь заходит не о людях и отделах, а о том, как именно общаются сервисы в конкретном сценарии — кто шлёт запрос, кто отвечает, что прилетает вебхуком, — это sequence. Это главный инструмент аналитика для описания интеграционного сценария. Когда вы проектируете API или интеграцию с внешним сервисом, вы рисуете sequence.

Диаграмма состояний — про жизненный цикл одной сущности. Если вопрос звучит как «в каких статусах бывает заказ и какие переходы между ними разрешены» — это конечный автомат, а не sequence. Sequence показывает один проход по сценарию во времени; состояния показывают все возможные состояния одной сущности и правила переходов. Подробнее — в записи про диаграммы состояний.

Пример: оплата через внешнего провайдера

Соберём всё вместе на реальном сценарии — оплата заказа через внешний платёжный провайдер. Участники: Клиент, Наш бэкенд, Платёжный провайдер, Банк. Покажем синхронные вызовы, ответы и фрагмент alt для двух исходов — успех и отказ.

sequenceDiagram
  participant K as Клиент
  participant B as Наш бэкенд
  participant P as Платёжный провайдер
  participant Bank as Банк
  K->>B: Оформить оплату заказа 123
  B->>P: Создать платёж (сумма, заказ)
  P-->>B: id платежа + ссылка на оплату
  B-->>K: Редирект на страницу провайдера
  K->>P: Ввести данные карты
  P->>Bank: Запрос авторизации
  Bank-->>P: Решение по платежу
  alt Оплата успешна
    P->>B: Вебхук: платёж оплачен (async)
    B->>B: Проверить подпись вебхука
    B-->>P: 200 OK
    B->>K: Заказ оплачен
  else Отказ банка
    P->>B: Вебхук: платёж отклонён (async)
    B-->>P: 200 OK
    B->>K: Оплата не прошла, повторите
  end

Пересказ диаграммы прозой (схему не прочитает ни поисковик, ни ИИ, ни коллега в спешке — поэтому дублируем словами). Время идёт сверху вниз, участников четыре: Клиент, Наш бэкенд, Платёжный провайдер и Банк.

Сначала Клиент синхронно зовёт наш бэкенд: «оформить оплату заказа 123». Наш бэкенд синхронно идёт к платёжному провайдеру с запросом «создать платёж» (передаёт сумму и номер заказа). Провайдер пунктирным ответом возвращает нам id платежа и ссылку на страницу оплаты. Наш бэкенд пунктирным ответом отдаёт Клиенту редирект на эту страницу. Дальше Клиент уже сам, напрямую, отправляет провайдеру данные карты. Провайдер синхронно запрашивает у Банка авторизацию, и Банк пунктирным ответом возвращает решение по платежу.

Дальше начинается фрагмент alt — ветвление на два взаимоисключающих исхода. В ветке «Оплата успешна» провайдер отправляет нашему бэкенду асинхронное сообщение — вебхук «платёж оплачен» (это не ответ на наш вызов, а новое событие, которое прилетает само). Наш бэкенд проверяет подпись вебхука (вызов сам к себе), отвечает провайдеру кодом 200 OK и сообщает Клиенту, что заказ оплачен. В ветке «Отказ банка» провайдер так же асинхронно шлёт вебхук «платёж отклонён», бэкенд отвечает 200 OK и сообщает Клиенту, что оплата не прошла и нужно повторить. Выполняется ровно одна из двух веток — в зависимости от решения банка.

Обратите внимание на ключевую деталь, которую sequence делает наглядной, а проза прячет: финальное подтверждение приходит не синхронным ответом на исходный запрос, а отдельным асинхронным вебхуком. Именно про это меня и спрашивал тестировщик. Как проектировать такие вебхуки — отдельная тема, разобрана в записи проектирование вебхуков.

Когда что брать

Вопрос, на который отвечаете	Нотация	Что в центре
Как системы обмениваются сообщениями во времени (интеграционный сценарий)	UML sequence	Сообщения между участниками, порядок, ответы
Кто что делает в бизнес-процессе, в каком порядке, кто за что отвечает	BPMN	Шаги, роли (дорожки), развилки процесса
В каких состояниях бывает одна сущность и какие переходы разрешены	Диаграмма состояний	Состояния и переходы одной сущности

Частые вопросы

Чем sequence-диаграмма отличается от BPMN?

Они отвечают на разные вопросы. BPMN описывает бизнес-процесс: кто (какая роль или отдел) что делает, в каком порядке, где развилки — в центре шаги и роли через дорожки. Sequence описывает обмен сообщениями между системами или компонентами во времени: кто кого зовёт, что приходит в ответ — в центре стрелки между участниками. Грубое правило: процесс с людьми и шагами — BPMN, общение сервисов в конкретном сценарии — sequence.

Что значат сплошная и пунктирная стрелки?

Сплошная стрелка с закрашенным наконечником (в mermaid ->>) — это синхронный вызов: отправитель зовёт и ждёт ответа. Пунктирная стрелка (-->>) — это ответ (return) на предыдущий синхронный вызов, а не новый запрос. Открытая стрелка без ответа обычно означает асинхронное сообщение — отправил и пошёл дальше, ответа здесь не ждёт (так рисуют события и вебхуки). Различать тип стрелки важно: от него зависит, синхронная это интеграция или асинхронная.

Зачем нужны фрагменты alt, opt, loop, par?

Это рамки, которые позволяют показать на одной диаграмме не только прямой сценарий. alt — ветвление «или-или» (выполняется одна из веток по условию, аналог if-else). opt — опциональный блок (выполнится, только если условие истинно, if без else). loop — цикл (блок повторяется, пока верно условие). par — параллельность (несколько блоков идут одновременно, порядок между ними не важен). Чаще всего аналитику нужен alt, чтобы показать ветку успеха и ветку ошибки, не рисуя две отдельные диаграммы.