Использование PlantUML для описания API. Визуализация для начинающих

Привет Хабр! Меня зовут Татьяна Ошуркова, я разработчик, аналитик и автор телеграм-канала IT Talks.

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

Но как начать использовать диаграммы в работе, если ранее вы не использовали их или работали с ними редко?

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

Теория и назначение диаграмм

Начнем с теории и рассмотрим назначение нескольких UML-диаграмм.

1. Диаграмма последовательности (Sequence Diagram). Описывает последовательность взаимодействий между объектами или системами во времени.

2. Диаграмма компонентов (Component Diagram). Показывает модульную структуру системы и связи между компонентами.

3. Диаграмма развертывания (Deployment Diagram). Отображает физическое размещение компонентов системы на серверах, устройствах или других инфраструктурных элементах.

4. Диаграмма активности (Activity Diagram). Показывает последовательность действий или шагов в процессе, включая ветвления, циклы и параллельные операции.

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

2 декабря я проведу бесплатный вебинар: «Построение диаграмм. Цели и задачи визуализации данных», где подробно разберу, как эффективно использовать различные виды диаграмм для описания требований. Запись на вебинар доступна по ссылке.

Практика и визуализация в документации

Постановка задачи

Нашей задачей будет описание API для системы управления заказами. Мы разрабатываем API, которое позволяет:

1. Управлять заказами:

   • Создавать новые заказы.

   • Получать статус заказа.

   • Отменять заказы.

2. Интегрироваться с внешними сервисами:

   • Проверка и обработка оплат.

   • Расчет стоимости доставки и отправка заказа.

3. Поддерживать очереди задач для асинхронной обработки операций.

4. Обеспечивать аутентификацию и авторизацию пользователей.

Рассмотрим построение нескольких диаграмм с использованием PlantUML.

Функционал API

Основные конечные точки API:

• POST /orders: Создание заказа.

• GET /orders/{id}: Получение информации о заказе.

• PATCH /orders/{id}/cancel: Отмена заказа.

• PATCH /orders/{id}/complete: Завершение заказа после оплаты и доставки.

Диаграмма компонентов

Эта диаграмма помогает визуализировать компоненты архитектуры системы и основные взаимодействия между её частями.

@startuml  package "Клиентская часть" {   [Мобильное приложение]   [Веб-приложение] }  package "Серверная часть API" {   [API Gateway]   [Сервис управления заказами]   [Сервис очередей задач] }  package "Внешние системы" {   [Платежный сервис]   [Сервис доставки]   [Сервис уведомлений] }  [Мобильное приложение] --> [API Gateway] [Веб-приложение] --> [API Gateway] [API Gateway] --> [Сервис управления заказами] [Сервис управления заказами] --> [Сервис очередей задач] [Сервис управления заказами] --> [Платежный сервис] [Сервис управления заказами] --> [Сервис доставки] [Сервис очередей задач] --> [Сервис уведомлений]  @enduml

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

Диаграмма последовательности. Создание заказа

Эта диаграмма описывает процесс создания нового заказа с использованием описанных выше запросов.

@startuml  participant Client participant API participant Database  Client -> API: POST /orders API -> Database: Insert new Order Database --> API: Order ID API --> Client: Order Created (ID: 456)  Client -> API: GET /orders/456 API -> Database: Fetch Order Details Database --> API: Order Data API --> Client: Order Details  Client -> API: PATCH /orders/456/cancel API -> Database: Update Order Status (cancelled) Database --> API: Succes API --> Client: Order Cancelled  Client -> API: PATCH /orders/456/complete API -> Database: Update Order Status (completed) Database --> API: Success API --> Client: Order Completed  @enduml

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

Диаграмма активности. Обработка задач в очереди

Очереди задач используются для асинхронной обработки операций, таких как уведомления, оплата и доставка.

@startuml  start :Получить задачу из очереди; if (Тип задачи == "Оплата") then (Да)   :Проверить статус оплаты;   if (Оплата подтверждена?) then (Да)     :Обновить статус заказа;     :Отправить уведомление клиенту;   else (Нет)     :Пометить заказ как "ошибка оплаты";   endif else (Нет)   if (Тип задачи == "Доставка") then (Да)     :Рассчитать доставку;     :Передать заказ в службу доставки;     :Обновить статус заказа;     :Отправить уведомление клиенту;   else (Нет)     :Логировать неизвестный тип задачи;   endif endif stop  @enduml

Диаграмма активности визуализирует логику обработки задач, что упрощает отладку и разработку.

Диаграмма развертывания

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

@startuml  node "Client" as client {     [Mobile App]      [Web App] }  cloud "API Gateway" as gateway {     [Order Management Service]     [Product Catalog Service] }  database "Main Database" as db {     [Customer Table]     [Order Table]     [Product Table]     [OrderItem Table] }  cloud "External Services" as external {     [Payment Gateway]     [Notification Service] }  client --> gateway : API Requests gateway --> db : Database Queries gateway --> external : External API Calls  @enduml

Диаграмма развертывания помогает в проектировании архитектуры и распределении компонентов.

Подведем итоги

Использование PlantUML для документирования API – эффективный способ визуализировать систему с разных сторон: от сценариев взаимодействия (диаграммы последовательности) до архитектуры (диаграммы развертывания).

Важно учитывать, что:

• Диаграммы последовательности тесно связаны с API-запросами, показывая их выполнение.

• Остальные диаграммы описывают данные, связи и инфраструктуру, но не отражают запросы напрямую.

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

Удачи в построении диаграмм на практике!