Диаграмма последовательности: как разобрать взаимодействие сервисов

Диаграмма последовательности отвечает на вопрос: кто кому отправляет сообщение и в каком порядке. Она полезна, когда словесное описание скрывает лишний запрос, неясную ответственность или пропущенный ответ. Начинайте с одного конкретного сценария, а не со схемы всей системы.

На Mentoring.digital построим учебный пример открытия карточки товара через API с кэшем. Схема описывает выбранный вариант взаимодействия, а не обязательную архитектуру любого каталога.

Сначала зафиксируйте границы сценария

Начало: пользователь открывает существующий товар с ID 42. Конец: интерфейс получает данные и показывает карточку. Внутри примера API сначала проверяет кэш, при промахе читает базу и сохраняет результат с ограниченным временем жизни.

Для первой схемы примем, что товар существует, хранилища доступны, а права на чтение уже проверены. Эти допущения нужно записать рядом со схемой. Ошибки доступа, отсутствие товара и недоступность базы потребуют дополнительных сценариев, а не молчаливого предположения, что они невозможны.

Выделите участников: пользователь, интерфейс каталога, API товаров, кэш и база. Не добавляйте каждый внутренний метод отдельной колонкой, если обсуждаете границы сервисов. Иначе схема станет подробной, но потеряет свой вопрос.

Сообщения и развилка в Mermaid

В диаграмме участники располагаются по горизонтали, последовательность читается сверху вниз. Ниже используется синтаксис Mermaid: actor обозначает пользователя, participant добавляет участника, alt и else описывают альтернативы.

sequenceDiagram
    actor Reader as Пользователь
    participant UI as Каталог
    participant API as API товаров
    participant Cache as Кэш
    participant DB as База товаров
    Reader->>UI: Открыть карточку товара
    UI->>API: GET /products/42
    API->>Cache: Найти product:42
    alt Значение найдено и пригодно
        Cache-->>API: Данные товара
    else Значения нет
        Cache-->>API: Промах
        API->>DB: Прочитать товар 42
        DB-->>API: Данные товара
        API->>Cache: Сохранить данные с TTL
        Cache-->>API: Сохранено
    end
    API-->>UI: 200 и данные товара
    UI-->>Reader: Показать карточку

Код можно вставить в редактор или Markdown-среду с поддержкой Mermaid. Обычный Markdown-редактор без такого расширения покажет исходный текст. Названия участников отделены от коротких технических идентификаторов, поэтому подписи можно менять без переписывания всех сообщений.

В этом примере сплошные стрелки используются для запросов, пунктирные для ответов. Такая договорённость упрощает чтение, но сама по себе не доказывает способ транспорта или синхронность реализации. Не выводите из формы стрелки, используется ли HTTP, очередь или прямой вызов: существенный протокол нужно подписать.

Как прочитать две ветки без противоречий

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

Условие «пригодно» требует определения в реальной задаче. Например, проверяется срок хранения и допустимость устаревших сведений. Для цены и остатка допустимая свежесть может отличаться от описания товара. Диаграмма помогает обнаружить этот вопрос, но не выбирает бизнес-правило за команду.

Не добавляйте loop там, где повторов нет. opt подходит для необязательной ветки с одним условием, alt для альтернатив. Если процесс запускает параллельные действия, последовательный рисунок не должен создавать впечатление, что второе обязательно ждёт первого.

Проверьте схему по вопросам команды

1. У каждого сообщения понятны отправитель, получатель и смысл данных?
2. Обе ветки приводят к ожидаемому завершению?
3. Условия ветвления не пересекаются и не оставляют неопределённый вариант?
4. Не появился лишний запрос к базе при попадании в кэш?
5. Какие ошибки намеренно вынесены в отдельные сценарии?

Следующее упражнение: нарисуйте случай отсутствующего товара с ответом 404 и отдельно решите, надо ли кэшировать такой результат. Затем сравните схему с контрактом API. Если в документах разные поля или разные коды ответа, исправлять нужно договорённость, а не только картинку.

Для описания ролей и взаимодействий пригодится обучение системному анализу. На разбор с ментором по системному анализу принесите исходный сценарий, схему и список допущений: так легче увидеть недостающие требования.