Plantuml в работе системного аналитика. Пиши uml диаграммы текстом, чтобы сэкономить время

А может есть инструмент, в котором можно поправить 10 диаграмм за раз? Давай поищем.

О каких диаграммах идет речь?

Системный аналитик в своей работе использует нотацию UML(Unified Modeling Language) для построения диаграмм процессов. Эти диаграммы помогают мне быстрее согласовывать документацию с архитектором и разработчиками, так как по ним скорее появляются вопросы, чем по текстовому описанию процесса.

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

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

   

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

   

Plantuml - что это?

Раньше я использовала для рисования диаграмм плагин в Confluence drawio или Microsoft Visio, который позволяет в графическом виде нарисовать диаграммы. Основная боль (для меня) у этих инструментов заключалась в том, чтобы поправить множество диаграмм надо открывать каждую, двигать элементы, стрелочки, а это время.

Изучив возможные решения, я пришла к plantuml (все возможности инструмента описаны тут). Это инструмент, который позволяет с помощью текста рисовать UML диаграммы. Его можно использовать через макрос в Confluence или плагин в Idea, что позволяет за раз править много диаграмм, так как это текст. Не верите? Давайте попробуем на примере.

Plantuml. Как им пользоваться?

Инструментом можно воспользоваться при помощи:

1. Онлайн редактора с синтаксисом plantuml https://www.planttext.com/ ;

2. Макроса в Confluence "PlantUML Macro";

3. Плагина "PlantUML Integration" для Idea, если пишите документацию рядом с кодом (скачать тут)

Поехали к практике!

Процесс:

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

Для нашего процесса построим диаграммы activity и sequence, используя plantuml.

Activity diagram

Как построить диаграмму?

1. Любая activity диаграмма начинается с @startuml и заканчивается @enduml

2. Дальше указываем начало start и окончания процесса stop

3. Затем выделяем группы, которые будут участвовать в процессе (прим. группы удобны для визуального чтения диаграммы) group... start ... end group

4. Внутри группы описываем действия или условия:

   1. действие без условия - :действие

   2. действие с условием - if (вопрос?) then (нет) ... else (да) ... endif

Для выделения жирным текстом используется <b>текст</b>. Для переноса текста на новую строку используется \n

В нашей задаче будут группы:

1. выбор конкретного обучения;

2. заполнение заявки на обучение;

3. оплата обучения.

В группе "Заполнение заявки на обучение" у нас будет действие с условием платный или бесплатный курс.

@startuml

start

   group <b>1.</b> Выбор конкретного обучения
   :Пользователь выбрал конкретное обучение \nсм. Диаграмму процесса 1;
   end group

   group <b>2.</b> Заполнение заявки на обучение
   :Пользователь заполнил данные \nв заявке на обучение (ФИО, email, телефон);

      if (Обучение платное?) then (нет)
      :Заявка на обучение принята;
      else (да)

         group <b>3.</b> Оплата обучения
         :Переходим к оплате обучения \nсм. Диаграмму процесса 3;
         end group

      endif

   end group

stop

@enduml

Sequence diagram

Как построить диаграмму?

1. Любая sequence диаграмма начинается с @startuml и заканчивается @enduml

2. Задаем участников процесса:

   1. Пользователь -  actor

   2. User Interface (UI) интерфейс (фронт сайта), Сервисы  - box и participant. (прим. для баз данных - database, очередей сообщений - queue)

3. Выделяем группы процессов. Это опциональный шаг

4. Описываем последовательность запросов с помощью конструкции участник -> участник : действие

5. Начинаем activate участник и заканчиваем deactivate участник линию жизни запроса (линия жизни запроса - это время)

6. Описываем альтернативные сценарии, если они есть с помощью alt...end. Как правило это обработка ошибок.

В нашей задаче будут участники процесса:

1. Пользователь

2. Сайт интерфейс - User Interface (UI)

3. Сайт - Сервис по работе с обучениями (Education)

Конструкция as позволяет присвоить короткое название участнику процесса actor "Пользователь" as user. Это удобно, когда надо поменять диаграмму для разных процессов или сократить количество символов в диаграмме.

Обозначения цвета в box различными цветами (например, #AliceBlue. Список html цветов тут) помогает выделить разные сервисы или обозначить, какой функционал относится к вашей команде, а что к другим командам.

Комментарий можно оставить с помощью синтаксиса note over участник: текст комментария

В нашей задаче будут группы:

1. выбор конкретного обучения;

2. заполнение заявки на обучение;

3. оплата обучения.

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

@startuml

actor "Пользователь" as user
box "Сайт" #AliceBlue
    participant "UI" as UI
    participant "сервис Education" as Education
end box

  group <b>1.</b> Выбор конкретного обучения
   note over user: см. Диаграмму процесса 1
  end group

  group <b>2.</b> Заполнение заявки на обучение
   user -> UI: Заполнить данные в заявке на обучение
   activate user
   activate UI
   UI -> Education: Отправить данные с заявкой на обучение
   activate Education
   Education -> Education: Проверка входящего запроса
   alt
        Education --> UI: Ответ с ошибкой
        UI --> user: Показать страницу об ошибке
   end

   Education -> Education: Сохранить данные заявки \nв базе данных
   Education --> UI: Ответ об успешном сохранении заявки
   deactivate Education

   group <b>3.</b> Курс платный, оплата обучения
    note over UI: Переходим к оплате обучения \nсм. Диаграмму процесса 3;
   end group

   group <b>4.</b> Курс ,бесплатный
    UI --> user: Показать, что пользователь \nуспешно записан на курс
    deactivate user
    deactivate UI
   end group
end group

@enduml

Иногда нехватка времени стимулирует поиск более удобных инструментов для рисования диаграмм. Я такой для себя нашла, это plantuml.

А вы в чем рисуете или пишете текстом диаграммы UML?