Как рисовать Sequence без боли и страданий в PlantUML

Привет! Меня зовут Настя, я старший системный аналитик в X5 Tech. Я рисую sequence-диаграммы каждый день на протяжении четырёх лет. За это время я прошла все круги ада по Данте, то есть попробовала разные инструменты для рисования этих самых диаграмм. Пока не встретила его – PlantUML. 

Что удивительно, инструмент довольно не новый, но тем не менее лучше него я пока не встречала. А ещё удивительно, что он не особо популярный. Когда мы запустили в управлении системного анализа первый воркшоп по PlantUML, за 3 минуты после анонса пришли 12 заявок от аналитиков разных грейдов – от Junior до Lead. 

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

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

Поэтому и появилась эта статья. 

Почему PlantUML?

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

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

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

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

Почему я так быстро переключилась на PlantUML? 

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

Как-то я даже рисовала sequence в Miro. Там мне понравилось больше всего из всех подобных платформ, потому что в Miro всё красивенько получается. 

Потом я узнала, что PlantUML – не единственный язык, который позволяет рисовать Sequence. Например, есть ещё D2 или MermaidJS. Есть ещё штука https://sequencediagram.org/, но, как по мне, она совсем на любителя. 

Я использую PlantUML по следующим причинам: 

1. Не надо рисовать стрелочки.

2. Мы ведём документацию в Confluence, и там есть плагин, в котором я всё и пишу. Это удобно. 

3. Ничего лишнего. В PlantUML можно сделать диаграмму, которая будет соответствовать стандартам sequence и при этом не будет ничем перегружена. 

4. Неплохая документация. В ней описано всё, что можно сделать, да ещё и с примерами.

Мой алгоритм построения диаграмм

Дополнительно всё можно найти в этих ваших Интернетах. 

Для примера возьму заказ кофе в кофейне. Это будет простая диаграмма, которые обычно мы не рисуем. В Sequence важно показать взаимодействие между компонентами системы или между несколькими системами. У меня задача другая — я не хочу писать, как правильно рисовать диаграммы. Я хочу показать, что PlantUML классный инструмент. 

Первый шаг – плагин в Confluence. Ищете PlantUML, выбираете, добавляете заголовок и у вас на странице появляется полотно для творчества. 

Второй шаг – написать @startuml и @enduml. Я не нашла сокровенной тайны, почему так надо делать (если знаете, напишите в комментариях). Я их всегда пишу в знак уважения к синтаксису, но без них диаграмма прекрасно будет отображаться.

@startuml   @enduml

Третий шаг – определение участников. Обычно конструкция определения участника выглядит так: 

<тип участника> <название> <опции>

Чаще всего я использую следующие типы участников: 

1. actor – рисуется в виде человечка, обозначает действующее лицо.

2. participant – рисуется в виде прямоугольника, обозначает какой-то компонент системы.

3. database – рисуется в виде значка базы данных и обозначает эту самую базу данных.

4. queue – рисуется в виде значка очереди и обозначает эту самую очередь.

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

Опции, которые я использую: 

1. псевдонимы as;

2. сортировка order.

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

<тип участника> <название> as <сокращенное_название>

Это сокращённое название нужно потом использовать в коде. Это удобно по двум причинам: 

1. если название на русском, то не придётся постоянно переключать раскладку;

2. если название длинное, его можно заменить одной или несколькими буквами и сэкономить кучу времени.

Есть важная деталь – в каком порядке вы напишете участников, в том порядке они и будут отрисованы. Если вам это неудобно, то можете использовать ключевое слово order и порядок участника. Опция order идёт после опции as.  

@startuml  actor Покупатель as cus order 1 actor Бариста as bar order 2 participant "Кассовый аппарат" as cash order 3 database Холодильник as ref order 5 participant "Рабочее место" as work order 4  @enduml

Четвёртый шаг – добавляем в диаграмму стрелки сообщений. Тут всё просто – берём участников, добавляем между ними стрелки и называем сообщение, которым они обмениваются. Конструкция такая: 

<участник><стрелка><участник>:<сообщение>

Стрелки тоже бывают разных видов, все они используются в диаграммах: 

1. синхронное сообщение обозначается ->

2. асинхронное сообщение обозначается ->>

3. ответное (или возвращаемое) сообщение обозначается —>

4. собственное сообщение обозначается комбинацией участник -> участник

Ответное (или возвращаемое) сообщение можно оформить двумя способами. 

Первый способ: 

участник1 -> участник2

участник1 <— участник2

Второй способ: 

участник1 -> участник2

участник2 —> участник1

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

@startuml  actor Покупатель as cus order 1 actor Бариста as bar order 2 participant "Кассовый аппарат" as cash order 3 database Холодильник as ref order 5 participant "Рабочее место" as work order 4  cus -> bar: сделать заказ bar -> ref: проверить наличие продуктов bar <-- ref: продукты в наличии bar -> cash: выставить оплату cash -> cash: сформировать оплату bar <-- cash: оплата готова cus <-- bar: просьба оплатить заказ cus -> bar: оплата bar -> cash: оплата bar <-- cash: принято bar -> ref: нужно молоко bar <- ref: вот молоко bar -> work: приготовление кофе bar <-- work: кофе готов cus <-- bar: вот ваш кофе  @enduml

Пятый шаг – добавляем альтернативные и опциональные сценарии. Можно ещё добавлять циклы и блоки, которые выполняются параллельно. 

Все такие блоки начинаются с ключевого слова, обозначающего вид блока, и заканчиваются ключевым словом end. Конструкция такая: 

<вид_блока><название_блока>

<что-то происходит>

end <вид_блока>

Первый вид блока – alt. Это альтернативный сценарий, обязательно с одной веткой else. Будет выглядеть примерно так: 

alt альтернативный сценарий

участник1 -> участник2: сообщение

else другая ветка

участник1 -> участник2: сообщение

end alt

Если вам нужен просто alt без else, то можете использовать второй вид блока – opt. Это опциональный сценарий, который может выполниться при определённом условии. Выглядит так: 

opt какое-то действие

участник1 -> участник2: сообщение

end opt

Третий вид блока – loop. Действия в нём повторяются несколько раз или какой-то период времени. Выглядит аналогично opt: 

loop 3 раза

участник1 -> участник2: сообщение

end loop

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

group какая-то группа

участник1 -> участник2: сообщение

end group

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

@startuml  actor Покупатель as cus order 1 actor Бариста as bar order 2 participant "Кассовый аппарат" as cash order 3 database Холодильник as ref order 5 participant "Рабочее место" as work order 4  cus -> bar: сделать заказ bar -> ref: проверить наличие продуктов bar <-- ref: продукты в наличии bar -> cash: выставить оплату cash -> cash: сформировать оплату bar <-- cash: оплата готова cus <-- bar: просьба оплатить заказ loop пока не будет оплачен заказ cus -> bar: оплата bar -> cash: оплата bar <-- cash: принято end loop group приготовление кофе alt заказали кофе на альтернативном молоке bar -> ref: нужно альтернативное молоко bar <- ref: вот молоко else заказали кофе на обычном молоке bar -> ref: нужно обычное молоко bar <- ref: вот молоко end alt bar -> work: приготовление кофе bar <-- work: кофе готов end group cus <-- bar: вот ваш кофе opt покупатель оставил чаевые cus -> bar: вот чаевые cus <-- bar: большое спасибо end opt  @enduml

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

1. ключевыми словами activate <участник> и deactivate <участник> – там, где вы их указываете, начинается и заканчивается активация.

2. конструкциями ++ и —

Ключевые слова activate и deactivate указываются после строки с сообщением, которую вы хотите активировать или деактивировать. 

Конструкции ++ и — выглядят так: 

участник1 -> участник2++: сообщение

участник2 -> участник 3—: сообщение

Как вы заметили, плюсы и минусы указываются только на втором участнике. Это важный нюанс. Нельзя указывать так: 

участник1++ -> участник2++: сообщение

Для такой конструкции будет ошибка. Если вам нужно активировать участник1, то после сообщения нужно указать activate участник1 или участник1++. 

Я в своих диаграммах использую только плюсы и минусы. Ключевые слова занимают много места. 

@startuml  actor Покупатель as cus order 1 actor Бариста as bar order 2 participant "Кассовый аппарат" as cash order 3 database Холодильник as ref order 5 participant "Рабочее место" as work order 4  cus -> bar++: сделать заказ cus++ bar -> ref++: проверить наличие продуктов bar <-- ref--: продукты в наличии bar -> cash++: выставить оплату cash -> cash: сформировать оплату bar <-- cash--: оплата готова cus <-- bar: просьба оплатить заказ loop пока не будет оплачен заказ cus -> bar: оплата bar -> cash++: оплата bar <-- cash--: принято end loop group приготовление кофе alt заказали кофе на альтернативном молоке bar -> ref++: нужно альтернативное молоко bar <- ref: вот молоко else заказали кофе на обычном молоке bar -> ref: нужно обычное молоко bar <- ref--: вот молоко end alt bar -> work++: приготовление кофе bar <-- work--: кофе готов end group cus <-- bar: вот ваш кофе opt покупатель оставил чаевые cus -> bar: вот чаевые cus <-- bar--: большое спасибо cus-- end opt

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

Первое – autonumber. Указываете это слово до всего описания сообщений, и они будут пронумерованы автоматически. В общем виде эта команда выглядит так: 

autonumber <число_с_которого_начнется_нумерация><шаг>

Если вы не указываете два параметра, то автонумерация по умолчанию начинается с цифры 1 с шагом 1. 

Второе – разделители. Очень удобно, когда большая диаграмма, и нужно поделить её на части. Конструкция такая: 

==<заголовок>==

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

…<заголовок>…

Четвёртое – разделение сообщений. Если у вас есть большие сообщения, которые  удлиняют вашу диаграмму, то их можно разделить. Тоже есть два способа: 

1. автоматический – с помощью команды skinparam maxMessageSize <число>, указывается в начале диаграммы и действует на все сообщения;

2. ручной – с помощью команды \n, пишите в то место, где нужно поделить сообщение.

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

@startuml  actor Покупатель as cus order 1 actor Бариста as bar order 2 participant "Кассовый аппарат" as cash order 3 database Холодильник as ref order 5 participant "Рабочее место" as work order 4  autonumber  cus -> bar++: сделать заказ cus++ bar -> ref++: проверить наличие продуктов bar <-- ref--: продукты в наличии ==оплата== bar -> cash++: выставить оплату cash -> cash: сформировать оплату bar <-- cash--: оплата готова cus <-- bar: просьба\nоплатить заказ ||| loop пока не будет оплачен заказ cus -> bar: оплата bar -> cash++: оплата bar <-- cash--: принято end loop ==готовка== group приготовление кофе ||| alt заказали кофе на альтернативном молоке bar -> ref++: нужно альтернативное молоко bar <- ref: вот молоко else заказали кофе на обычном молоке bar -> ref: нужно обычное молоко bar <- ref--: вот молоко end alt bar -> work++: приготовление кофе bar <-- work--: кофе готов end group ...через 3 минуты... cus <-- bar: вот ваш кофе opt покупатель оставил чаевые cus -> bar: вот чаевые cus <-- bar--: большое спасибо cus-- end opt  @enduml

PlantUML и ChatGPT

ChatGPT прекрасно может работать с PlantUML. Тут работает классическое правило – хотите хороший результат, напишите детальный запрос. Для примера можем попросить просто написать код для PlantUML с sequence-диаграммой работы бариста.

Запрос: Напиши код для plantuml с sequence-диаграммой работы бариста.

@startuml actor Customer actor Barista participant Queue participant Database  Customer -> Queue: Заказать кофе Queue -> Barista: Передать заказ Barista -> Database: Записать заказ Database --> Barista: Подтверждение записи Barista -> Barista: Проверить наличие ингредиентов Barista -> Database: Обновить количество ингредиентов Database --> Barista: Подтверждение обновления Barista -> Barista: Приготовить кофе Barista -> Queue: Сообщить о готовности заказа Queue --> Customer: Оповестить о готовности  Customer -> Barista: Забрать заказ Barista -> Customer: Передать кофе Customer -> Barista: Оставить чаевые @enduml

Результат плохой: непонятно, что это за участники, не хватает активаций. Расположение участников тоже странное, если очередь – это физическая очередь, то зачем она вообще здесь. 

Но можно попробовать сформировать более конкретно. 

Запрос: Мне нужен код sequence-диаграммы для plantuml. В диаграмме должно быть 5 участников: покупатель, бариста, касса, рабочее место и холодильник. Обязательно должны быть активации и деактивации, один альтернативный сценарий с выбором молока (альтернативное или обычное) и опциональный блок для оставления чаевых. Хорошо бы добавить нумерацию сообщений. 

@startuml autonumber actor Customer participant Barista participant CashRegister as "Cash Register" participant WorkStation as "Work Station" participant Fridge as "Fridge"  Customer -> Cash Register: 1. Сделать заказ activate Cash Register Cash Register -> Barista: 2. Передать заказ deactivate Cash Register  activate Barista Barista -> Fridge: 3. Проверить наличие ингредиентов activate Fridge Fridge --> Barista: 4. Подтверждение наличия ингредиентов deactivate Fridge  alt Выбор молока     Customer -> Barista: 5. Выбрать обычное молоко     Barista -> Fridge: 6. Достать обычное молоко     Fridge --> Barista: 7. Обычное молоко else     Customer -> Barista: 5. Выбрать альтернативное молоко     Barista -> Fridge: 6. Достать альтернативное молоко     Fridge --> Barista: 7. Альтернативное молоко end  Barista -> WorkStation: 8. Приготовить кофе activate WorkStation WorkStation -> Customer: 9. Передать кофе deactivate WorkStation deactivate Barista  opt Оставить чаевые     Customer -> Cash Register: 10. Оставить чаевые     activate Cash Register     Cash Register -> Barista: 11. Сообщить о чаевых     deactivate Cash Register end @enduml

В результате мы получим ошибку, потому что ChatGPT в коде у участника Cash Register оставил пробел. Можно попросить исправить. 

Запрос: Исправь ошибку с Cash Register, там не должно быть пробела.

@startuml autonumber actor Customer participant Barista participant CashRegister as "Cash Register" participant WorkStation as "Work Station" participant Fridge as "Fridge"  Customer -> CashRegister: 1. Сделать заказ activate CashRegister CashRegister -> Barista: 2. Передать заказ deactivate CashRegister  activate Barista Barista -> Fridge: 3. Проверить наличие ингредиентов activate Fridge Fridge --> Barista: 4. Подтверждение наличия ингредиентов deactivate Fridge  alt Выбор молока     Customer -> Barista: 5. Выбрать обычное молоко     Barista -> Fridge: 6. Достать обычное молоко     Fridge --> Barista: 7. Обычное молоко else     Customer -> Barista: 5. Выбрать альтернативное молоко     Barista -> Fridge: 6. Достать альтернативное молоко     Fridge --> Barista: 7. Альтернативное молоко end  Barista -> WorkStation: 8. Приготовить кофе activate WorkStation WorkStation -> Customer: 9. Передать кофе deactivate WorkStation deactivate Barista  opt Оставить чаевые     Customer -> CashRegister: 10. Оставить чаевые     activate CashRegister     CashRegister -> Barista: 11. Сообщить о чаевых     deactivate CashRegister end @enduml

В целом даже похоже на то, что сделала я сама. Большое отличие в том, что для ChatGPT покупатель взаимодействует с кассой сам. Хотя в таком случае логичнее назвать этого участника как-то иначе. 

Забавно, что ChatGPT применил команду autonumber и сам пронумеровал сообщения. 

Заключение

Надеюсь, что эта статья помогла вам в освоении PlantUML. И в понимании того, что PlantUML – лёгкий инструмент. 

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

Если хотите узнать больше возможностей инструмента, то рекомендую использовать документацию: https://plantuml.com/ru/sequence-diagram. И ещё у них есть неплохой редактор, который сразу будет вам показывать всё то, что вы напишете: http://www.plantuml.com/plantuml/uml/.