Диаграммы без боли и страданий: PlantUML14.06.2023 10:31

Системный аналитик всегда и везде сталкивается с бесконечным количеством диаграмм разного вида, с нотациями (правилами), чтобы нарисовать данные диаграммы и с бесконечным количеством инструментов для их описания. Но мало кто говорит о таком инструменте, как PlantUML. 

Лично мне завесу тайны приоткрыл Альфа-Банк, здесь документация ведется рядом с кодом, и схемы логичнее описывать тоже кодом. Но это не так страшно и не так сложно (почти) как кажется. Давайте я приоткрою ящик Пандоры и сниму кармическое проклятье с этого инструмента. 

Рада представить обделённого вниманием язык и инструмент для создания диаграмм — PlantUML, который использует текстовый формат для описания бизнес-процессов, диаграмм классов, состояний, последовательностей и многих других видов диаграмм. 

Хотелось бы перейти сразу к преимуществам данного инструмента, но давайте сначала вспомним боль, которую вы испытываете, когда рисуете диаграмму в графическом редакторе:  

• СТРЕЛОЧКИ!!! (если вы когда-нибудь рисовали диаграмму, you know what i mean).

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

• Потеря исходников (есть картинка, а исходника нет). Соответственно, чтобы поправить схему надо перерисовать ВСЕ стрелочки.

• Требования специализированного ПО. Слава draw.io, конечно, но многие до сих пор используют всякие Aris, Bizagi, Enterprise architect.

• И, как следствие, нет понимания, как использовать данное ПО (один Visio чего только стоит).

 Что же дает PlantUML?

• Текстовое описание блоков, стрелок, которые можно отредактировать, используя несколько слов. 

• Разработчики любят код, PlantUML — это тоже код, а значит, что если разработчику показать эту статью, то он не только сможет читать данную диаграмму, а более того, сможет её даже сам нарисовать.

• Если положить схему в код и залить в git, то исходник точно никуда не денется.

• Для PlantUML много не надо — достаточно браузера, в котором вы сможете открыть онлайн-редактор или же Confluence. 

• У PlantUML простой синтаксис, который легко понять и использовать. Он не требует дополнительного обучения для начала работы.

Разобрались, почему PlantUML классный, погнали к практике.  

Где можно описывать диаграммы?  

№1. Самый простой способ — онлайн-редактор с синтаксисом PlantUML.

Будьте аккуратны, в некоторых (неофициальных) редакторах используется устаревший синтаксис, который может отличаться от гайда.

Для тех, кому скучно живется — локальная установка.

№2. Для тех, кто ведет документацию в Confluence — макрос «PlantUML Macro». Из минусов — не отрисовывает диаграмму на ходу, но если нажать изменить макрос, то можно в небольшом экране увидеть, отрисовалась диаграмма или есть ошибка.

№3. Для тех, кто пишет документацию рядом с кодом — плагин «PlantUML Integration» для Idea.

Какие диаграммы можно описывать: практика 

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

Диаграмма последовательностей (она же sequence diagram)

Интеграции — наше всё. Согласование интеграций — тоже наше всё. Поэтому в работе системного  аналитика очень важно уметь быстро и умело построить данную диаграмму, чтобы потом быстро и умело согласовать данную интеграцию, и быстро и умело обсудить диаграмму с командой.

Давайте попробуем описать такую диаграмму на примерах.

Вы так или иначе сталкивались с тем, что вам необходимо получить выписку по вашему счету. Начнём с простого — нам необходимо отобразить, в целом, доступный список справок по счету. 

@startuml

actor "Front" as front

participant "Сервис справок" as report
database "База данных" as db

front -> report: Получение список справок
activate report
report -> db:  Получение список справок из бд
activate db
db --> report:  Список справок
deactivate db
report -> front: Список справок
deactivate report

@enduml

Какие ключевые слова здесь есть:  

1. startuml/ enduml — начало/ окончание любой диаграммы в PlantUML;

2. actor/participant/database — то, как участник будет нарисован (есть и еще, смотри в гайде);

3. activate/ deactivate — начало/окончание «линии жизни» участников процесса;  

4. →/ --> — виды стрелок, на самом деле их очень много, но это базовые. 

Лайфхак. Тут можно посмотреть решение, как уменьшить описание диаграммы вдвое, но при этом картинка будет такая же (удалила activate/ deactivate, заменив на ++/-- соответственно).

@startuml

actor "Front" as front

participant "Сервис справок" as report
database "База данных" as db

front -> report++: Получение список справок
report -> db++:  Получение список справок из бд
db --> report--:  Список справок
report -> front--: Список справок

@enduml

Easy-peasy, lemon squeezy!

А теперь давайте попробуем описать задачу с процессом посложнее. Например, мы хотим сформировать выписку по счету (да-да, та самая справка, которую берём для предоставления в посольство на получение визы). 

@startuml
actor "Front" as front
autonumber
box "Back" #LightBlue
participant "Сервис справок" as report
participant "Сервис счетов" as account
participant "Сервис клиентов" as customer
participant "Сервис скоринга клиентов" as check
participant "Сервис формирования pdf" as pdf
database "База данных" as db
end box

front -> report++: Получение выписку по счету
report -> account++: Получение информации по счету
account -> db++:  Получение информации по счету
db -> db:  Получение информации по счету
db --> account--:  Информация по счету
account --> report--:  Информация по счету
report -> customer++: Получение информации по клиенту
customer -> db++:  Получение информации по клиенту
db -> db:  Получение информации по клиенту
db --> customer--:  Информация по клиенту
customer --> report--:  Информация по клиенту
report -> check++: Проверка клиента
alt Клиент не прошел проверку
check--> report--: Клиенту нельзя выдать выписку по счету
report--> front: Отказ в выдачи выписки по счету
else Клиент прошел проверку
report -> pdf++: Отправка данных для \nформирования выписки по счету
pdf -> pdf: Формирование выписки по счету
pdf --> report--:  Выписка по счету
report -> front--: Выписка по счету
end
@enduml

Новые ключевые слова:

1. box/ end box — группировка участников, удобно обозначать, например, в какой подсети находятся участники;

2. #LightBlue — цвет у элемента box.

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

4. \n — перенос длинных текстов, не забывайте этим пользоваться, помогает не раздуть диаграмму.

5. alt — добавили несколько альтернативных фрагментов (alternative), выполняется только тот фрагмент, условие которого истинно.

И ещё на заметку несколько популярных:

• opt — необязательный (optional), выполняется, только если условие истинно, эквивалентно alt с одной веткой;

• par — параллельный (parallel), все фрагменты выполняются параллельно;

• loop — цикл (loop), фрагмент может выполняться несколько раз;

• group — выделит указанный фрагмент в рамку.

И вот что вышло:

​​

Диаграмма активности (она же activity diagram)

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

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

@startuml
start
:Клиент нажал на раздел "Справки";
:Фронт отправил запрос на \nполучение списка справок;
:Сервис справок отправил запрос в БД;
:Сервис справок получил список справок;
:Фронт отобразил список справок;
stop

@enduml

 Вышло совсем скучно, но тем не менее, нужно подметить ключевые слова:

1. startuml/enduml — начало/окончание любой диаграммы в PlantUML;  

2. start/stop — начало/окончание любой диаграммы активности;

3. действие описываем по следующей структуре:   : Получение данных;

Вот что получилось.

Погнали к диаграмме посложнее (процесс формирования pdf-файла выписки по счету).

@startuml
start
:Клиент заказал "Выписку по счету";
group 1. Получение данных по клиенту и счету из БД 
:Сервис Справок отправил запрос на \nполучение данных по клиенту;
:Сервис Справок отправил запрос на \nполучение данных по счету;
end group
group 2. Проверка клиента 
:Сервис справок отправил запрос в систему Скоринга;
end group
if (Клиент проходит проверку?) then (нет)
:Отправляем клиенту ошибку;
else (да)
group 3.  Формирование печатной формы 
:Сервис справок отправляет данные \nв сервис формирования pdf;
end group
:Сервис справок получил выписку по счету;
:Фронт отобразил выписку по счету;
endif
stop
@endumll

Из интересного:  

1. Добавились условия:  
   if (Условие) then (да/нет)
   : Действие;
   else (да/нет)

2. Добавилась группировка group /end group для удобства чтения схемы. 

Теперь потренируемся

А теперь попробуйте описать рассмотренные выши диаграммы самостоятельно.  

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

• клиент на главном экране в мобильном приложении нажимает на раздел «Карта отделений и банкоматов»;

• далее переходит на страницу со списком отделений и банкоматов. 

В данном процессе участвуют следующие системы:

• банковское мобильное приложение — система, через которую пользователь просматривает банкоматы и отделения;

• система, агрегирующая информацию по банкоматам и отделениям — система банкоматов и отделений;

• и система карт — в нашем случае это API Яндекс.Карт.

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

Диаграмма последовательностей ещё раз

А теперь пожёстче.

Диаграмма последовательностей по хардкору

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

Мой вариант здесь

Заключение

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

Он может служить верой и правдой не только аналитикам, но и другим членам scrum-команды и экономить время при описании диаграмм почти любой сложности. Раскрою секрет — самая большая схема в статье заняла примерно 30 минут. А сколько у вас займет времени на подготовку подобной диаграммы в PlantUML или в любом другом инструменте?

© Habrahabr.ru