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

«UML диаграмма последовательностипоказывает, как участники взаимодействуют во времени. Она полезна для документирования «сценария использования», потока API, бизнес-процесса или сценария системы. Время обычно движется сверху вниз; горизонтальное расположение показывает, кто участвует, а не точную меру прошедшего времени.

PlantUMLпозволяет описывать диаграмму в виде текста. «Редактор VPasCode от Visual Paradigmсочетает редактор кода с живым предварительным просмотром и помощью ИИ для генерации, изменения и исправления кода диаграмм. Хороший рабочий процесс — использовать ИИ для создания черновика, а затем самостоятельно проверять и дорабатывать код PlantUML.

1. Базовая структура

«диаграмма последовательности PlantUMLначинается с «@startuml» и заканчивается «@enduml». Участники обычно перечисляются до сообщений, чтобы вы могли контролировать их имена и порядок.

@startuml
actor Клиент
participant Браузер
participant "API заказов" как API
database "База данных заказов" как DB

Клиент -> Браузер: Разместить заказ
Браузер -> API: POST /orders
API -> DB: Сохранить заказ
DB --> API: ID заказа
API --> Браузер: 201 Created
Браузер -> Клиент: Показать подтверждение
@enduml

Отображаемая метка участника может быть заключена в кавычки, с как предоставляя более короткое псевдоним для использования в сообщениях. Общие ключевые слова участников включают actor, participant, boundary, control, entity, database, и коллекции. Используйте ключевое слово, которое наилучшим образом передаёт роль участника; оно не навязывает определённую архитектуру.

2. Чтение сообщений и времени

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

• -> — это сплошная стрелка сообщения, обычно используемая для запроса или вызова.

• --> — это пунктирная стрелка, часто используемая для ответа или возврата.

• ->> и -->> используют открытые наконечники стрелок в распространённых стилях PlantUML.

• : текст добавляет метку сообщения.

Выберите последовательное соглашение для вызовов и ответов. Диаграммы UML передают взаимодействие; они автоматически не гарантируют, что реализация следует изображённому протоколу.

3. Активации и время жизни участников

Активации могут показывать, когда участник выполняет работу. Используйте activate и деактивировать, или сокращённо ++ и -- на стрелках сообщений.

@startuml
actor User
participant "Login API" as API
database Users

User -> API: Предоставить учётные данные
activate API
API -> Users: Найти учётную запись
activate Users
Users --> API: Запись учётной записи
deactivate Users
API --> User: Результат входа
deactivate API
@enduml

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

4. Условия, альтернативы и повторения

Используйте объединённые фрагменты для отображения потока управления. Ключевое слово fragment начинает блок, else разделяет альтернативы, где это применимо, и end закрывает его. Охранные условия записываются в квадратных скобках.

Альтернативные пути: alt и иначе

@startuml
actor Пользователь
участник "API входа" как API
база данных Пользователи

Пользователь -> API: Отправить имя пользователя и пароль
API -> Пользователи: Проверить учетные данные
Пользователи --> API: Результат совпадения

alt [учетные данные верны]
  API --> Пользователь: Вернуть токен сессии
else [учетные данные неверны]
  API --> Пользователь: Вернуть ошибку аутентификации
end
@enduml

altподходит, когда пути взаимно исключают друг друга. Используйте метки, которые делают условия понятными.

Опциональное поведение: opt

@startuml
actor Покупатель
участник Оформление заказа
участник "Служба электронной почты" как Email

Покупатель -> Оформление заказа: Завершить покупку
Оформление заказа --> Покупатель: Подтверждение заказа

opt [покупатель согласился на получение электронной почты]
  Оформление заказа -> Email: Отправить чек
  Email --> Оформление заказа: Принято
end
@enduml

Повторение: цикл

@startuml
участник "Пакетная задача" как Job
участник "API платежей" как API

cycle [для каждой ожидающей оплаты]
  Job -> API: Отправить оплату
  API --> Job: Результат оплаты
end
@enduml

Разместите повторяющееся действие внутри фрагмента и чётко укажите условие или область цикла.

5. Параллельные и сгруппированные взаимодействия

Используйте par когда взаимодействия происходят одновременно или их порядок не имеет значения. Используйте group для маркировки набора сообщений без указания конкретной структуры управления потоком.

@startuml
участник "Сервис заказов" как Orders
участник "Сервис инвентаризации" как Inventory
участник "Сервис уведомлений" как Notify

Orders -> Orders: Заказ принят

параллельно Резервирование товара
  Orders -> Inventory: Резервировать товары
  Inventory --> Orders: Результат резервирования
иначе Уведомить клиента
  Orders -> Notify: Отправить обновление заказа
  Notify --> Orders: Принято
конец
@enduml

Используйте параллельно только тогда, когда параллельность имеет смысл. Если одно действие должно завершиться перед началом другого, показывайте сообщения последовательно.

6. Примечания, ссылки и визуальная группировка

Примечания могут прояснять допущения, ограничения или решения. ref фрагмент может направлять читателей к другой диаграмме или отдельно документированному взаимодействию.

@startuml
актор Клиент
участник "Интерфейс оформления заказа" как UI
участник "Сервис оплаты" как Pay
участник "Проверка мошенничества" как Fraud

Клиент -> UI: Оплатить заказ
UI -> Pay: Авторизовать платеж
Pay -> Fraud: Оценить транзакцию

примечание справа от Fraud
  Правила оценки рисков поддерживаются
  вне этого взаимодействия.
конец примечания

Fraud --> Pay: Результат оценки риска
Pay --> UI: Результат авторизации
UI --> Клиент: Показать результат
@enduml

Примечания должны добавлять контекст, а не повторять подписи сообщений. Если диаграмма становится перегруженной, разделите её на сфокусированные сценарии и используйте ссылки или ссылки на документацию для их связывания.

7. Создание и доработка диаграмм в VPasCode

VPasCode поддерживает редактирование PlantUML с живым отображением, а также генерацию диаграмм с помощью ИИмодификацию кода и исправление синтаксиса. Точный интерфейс и доступность функций могут меняться, но общий рабочий процесс выглядит так:

1. Откройте VPasCode и выберите или введите PlantUML.

2. Опишите взаимодействие или вставьте черновик PlantUML в редактор.

3. Проверяйте отрендеренный предварительный просмотр по мере доработки исходного кода.

4. Попросите ИИ внести конкретное изменение, например: «добавить путь для невалидных учётных данных с использованием «alt.”

5. Проверьте полученный код и диаграмму на соответствие синтаксису и корректность работы системы.

6. Экспортируйте или поделитесь готовой диаграммой, используя доступные в редакторе опции.

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

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

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

8. Более полный пример: оформление заказа с отказом в оплате

Этот пример объединяет псевдонимы участников, активации и альтернативный путь.

@startuml
title Оформление заказа и авторизация платежа

актор Клиент
граница "Интерфейс оформления заказа" как UI
контроллер "Сервис заказов" как Orders
участник "Платёжный шлюз" как Pay
база данных "База данных заказов" как DB

Клиент -> UI: Отправить оформление
UI -> Orders: Создать ожидающий заказ
активировать Orders

Orders -> DB: Сохранить ожидающий заказ
DB --> Orders: ID заказа

Orders -> Pay: Авторизовать платёж
активировать Pay

alt [платёж одобрен]
  Pay --> Orders: Код авторизации
  деактивировать Pay

  Orders -> DB: Отметить заказ подтверждённым
  DB --> Orders: Обновлено
  Orders --> UI: Заказ подтверждён
  UI --> Клиент: Показать подтверждение
else [платёж отклонён]
  Pay --> Orders: Причина отклонения
  деактивировать Pay

  Orders -> DB: Отметить заказ неудачным
  DB --> Orders: Обновлено
  Orders --> UI: Платёж отклонён
  UI --> Клиент: Показать возможность повторной попытки
end

deactivate Orders
@enduml

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

9. Практические рекомендации по моделированию

• Держите диаграмму сфокусированной.Показывайте один сценарий или closely related набор путей. Выносите глубокие детали, которые отвлекают от основного взаимодействия.

• Называйте участников по их ответственности. Предпочитайте метки, такие как “Сервис заказов" или “Платёжный шлюз" вместо нечётких меток, таких как “Система".

• Показывайте осмысленные границы.Различайте пользователя, клиент, внутренние сервисы, базы данных и внешние системы, когда это помогает читателям понять ответственность.

• Используйте понятные метки сообщений.Включите операцию, событие или важный результат; избегайте меток, которые просто говорят «процесс».

• Моделируйте значимые пути сбоев.Включайте соответствующие таймауты, отклонения, повторные попытки или сбои валидации, если они влияют на сценарий.

• Точно используйте фрагменты. alt означает альтернативные пути, opt означает опциональное поведение, loop означает повторение, а par означает параллельное поведение.

• Избегайте шума реализации.Не диаграммируйте каждый геттер, внутренний метод или низкоуровневую деталь, если аудитория в этом не нуждается.

• Делайте исходный код поддерживаемым.Используйте псевдонимы для длинных имён, согласованную систему именования и краткие комментарии или заметки для важных допущений.

10. Типичные ошибки и контрольный список для проверки

Если диаграмма не отображается, проверьте, что @startuml и @enduml присутствуют, блоки фрагментов имеют соответствующие end операторы, псевдонимы используются последовательно, и все точки назначения сообщений ссылаются на определённые участники. Также проверьте, не была ли случайно вставлена в исходный код PlantUML синтаксиса из другого языка диаграмм.

Перед публикацией проверьте два момента:

• Синтаксис:Она рендерится? Закрыты ли фрагменты? Последовательны ли участники и псевдонимы?

• Смысл:Правильны ли участники и направления сообщений? Включены ли важные пути ошибок? Точно ли представлены внешние системы и хранилища данных?

Самый эффективный рабочий процесс диаграмм как кода объединяет читаемый исходный код, быструю визуальную обратную связь и проверку предметной областью. PlantUML обеспечивает явный контроль над нотацией взаимодействий, в то время как VPasCode может ускорить черновик и итерации; окончательным авторитетом в точности диаграммы остаётся поведение системы, которое она должна описывать.

Эта статья также доступна на Deutsch, English, Español, فارسی, Français, Bahasa Indonesia, 日本語, Polski, Portuguese, Việt Nam, 简体中文 and 繁體中文