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

83523eda19efe74351d8abcee56ccacb.png

Привет Хабр! Меня зовут Татьяна Ошуркова, я разработчик, аналитик и автор телеграм-канала 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

7a4d572b5b1ebef59c1d95886a7a3671.png

Диаграмма компонентов показывает взаимодействие клиентских приложений, серверной части 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

caab221cd16490693e8f632e001ced57.png

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

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

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

@startuml

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

@enduml

b7c7a7001a7035fec72b5f879918fb59.png

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

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

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

@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

cef34f97fdf5e565ccc0bdae616df341.png

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

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

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

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

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

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

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

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

IT Talks | Ошуркова Татьяна

t.me

© Habrahabr.ru