Нужен ли навык создания схем бэкенд-разработчику? Если вы активно взаимодействуете с аналитиками, лидерами команд или руководите джунами, то схемы станут удобным способом презентовать, объяснять или согласовывать архитектурные решения. Наш разработчик Костя Н. использовал инструменты Draw.io и PlantUML в повседневной работе и решил получше разобраться в их возможностях. В этой статье Костя расскажет о практическом аспекте использования схем — какие действительно полезны, а какие бэкендеру не пригодятся.
Draw.io
В Confluence существует два основных способа создания и редактирования схем: Draw.io и PlantUML.
Draw.io, также известный как diagrams.net, является популярным инструментом для создания схем и диаграмм. Это мощный инструмент, однако его использование связано с определенными ограничениями, такими как низкая производительность в Confluence и сложность интеграции с системами контроля версий. Несмотря на это, низкий порог входа делает Draw.io хорошим выбором для быстрой визуализации идей.
Преимущества Draw.io
- Полный контроль над дизайном позволяет создавать максимально аккуратные и детализированные схемы.
- Понятный интерфейс позволяет быстро начать работу.
- Идеально подходит для живых демонстраций во время совещаний и оперативного внесения изменений в схему по ходу встречи.
Недостатки Draw.io
- Схемы хранятся в формате XML, что затрудняет отслеживание изменений и интеграцию с Git.
- При работе с большими проектами и сложными диаграммами инструмент может ощутимо тормозить.
- Автоматическое размещение элементов может приводить к непредсказуемым сдвигам и последующей ручной корректировке.
Моя рекомендация: используйте плагины для улучшения производительности. Когда Draw.io запущен через Confluence то при большом количестве схем будут задержки. Используйте плагин для IDE, например, IntelliJ, который позволяет создавать и редактировать диаграммы локально, и затем копируйте их в Confluence. Это снижает зависимость от качества интернет-соединения, что особенно актуально при подключении через VPN.
Костя, бэкенд-разработчик
PlantUML
PlantUML является мощным инструментом для создания диаграмм, особенно для тех, кто предпочитает работать с кодом. Его декларативный подход обеспечивает быструю визуализацию архитектуры и процессов, что упрощает процесс создания и изменения диаграмм, особенно в больших проектах. Но вместе с этим настройка элементов может быть трудоемкой и требовать знания синтаксиса PlantUML.
Преимущества PlantUML
- Благодаря текстовому описанию создание и изменение диаграмм происходит значительно быстрее по сравнению с Draw.io.
- Поскольку диаграммы описываются кодом, они легко интегрируются с системами контроля версий.
- Позволяет сосредоточиться на сути диаграммы, описывая, что должно быть представлено, а не как именно это должно выглядеть.
Минусы и ограничения PlantUML
- Если требуется точное расположение элементов диаграммы, это может потребовать значительных усилий и экспериментов с синтаксисом PlantUML.
- Новичкам может потребоваться время для освоения синтаксиса.
Создаем простую диаграмму в PlantUML
Предположим, вам необходимо быстро создать диаграмму сущностей для одной из функций вашего проекта. Этот простой код генерирует диаграмму, описывающую связь между пользователями и заказами. В отличие от графических инструментов, где вам пришлось бы вручную размещать блоки и соединять их стрелками, в PlantUML можно быстро настроить структуру диаграммы, корректируя текстовое описание.
@startuml
title Диаграмма настроек
skinparam linetype ortho
entity dispensers_settings_pack {
*id : bigint
--
group_id : bigint
total_production : numeric
}
entity dispensers_settings {
* dispensers_settings_pack_id : bigint
* dispenser_id : bigint
--
production : numeric
}
entity dispersers_settings_status_history {
*id : bigint
--
*dispensers_settings_pack_id : bigint
status : text
user_name : text
email : text
created_at : timestamp
}
dispensers_settings_pack }|-- dispensers_settings
dispensers_settings_pack }|-- dispersers_settings_status_history
@enduml
Типы диаграмм в PlantUML
При выборе инструментов для визуализации архитектуры и процессов в бэкенд-разработке важно понимать, какие типы диаграмм действительно полезны, а от каких можно отказаться. Я разбил диаграммы на 3 класса: полезные, сомнительные и ненужные.
Ненужные диаграммы
Эти типы диаграмм редко находят применение в задачах бэкенд-разработчика.
- EBNF (Extended Backus–Naur Form). Используется для описания синтаксиса языков программирования.
- ASCII Math. Предназначен для рисования математических формул в текстовом формате.
- MindMap. Полезны для мозговых штурмов, но в контексте бэкенд-разработки часто оказываются избыточными.
- Gantt диаграммы. Обычно используются проектными менеджерами для планирования сроков и ресурсов.
- Use Case диаграммы. Хотя могут быть полезны для понимания требований системы, их создание — задача системных или бизнес-аналитиков.
Сомнительные диаграммы
Эти диаграммы могут быть полезны в определенных ситуациях.
- Диаграмма классов (Class Diagram). Полезна для визуализации объектов и их взаимодействий. В крупных проектах может быть избыточной.
- Диаграмма развертывания (Deployment Diagram). Описывает физическое развертывание программного обеспечения. Обычно настраивается DevOps-специалистами.
- Диаграмма состояний системы (State Diagram). Полезна для отображения состояний объектов или системы. Требует глубокого понимания синтаксиса PlantUML.
- Сетевая диаграмма (Network Diagram). Описывает сетевую инфраструктуру и подключения. Чаще используется DevOps-инженерами.
- Archimate диаграммы. Высокоуровневые архитектурные диаграммы, предназначенные для архитекторов.
Полезные диаграммы в PlantUML
JSON диаграммы
PlantUML позволяет быстро визуализировать большие JSON-структуры. Например, вы можете загрузить большой JSON-файл, и за считанные секунды он сгенерирует диаграмму, отображающую взаимосвязи между полями. Это особенно полезно при работе с API или конфигурационными файлами, где необходимо понять структуру данных.
YAML диаграммы
YAML-диаграммы помогают визуализировать конфигурационные файлы или структуры данных. При развертывании микросервисов с использованием YAML-конфигураций, диаграмма позволяет быстро увидеть, как различные компоненты взаимодействуют друг с другом.
Regex диаграммы
Regex-диаграммы облегчают понимание структуры и работы регулярных выражений, особенно когда регулярка становится сложной и трудноразбираемой.
@startregex
^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$
@endregex
Information Engineering Diagram
IE-диаграммы отображают сущности, их атрибуты и связи между ними. Они полезны при проектировании баз данных, когда требуется согласовать структуру между командами или документировать ключевые сущности системы. PlantUML поддерживает указание типов данных, модификаторов видимости и внешних ключей (FK), что делает диаграммы детализированными и информативными.
Sequence Diagram
Диаграмма последовательностей, один из самых популярных типов диаграмм в UML. Эта диаграмма используется для объяснения того, как различные компоненты системы взаимодействуют друг с другом во времени. С помощью PlantUML можно быстро изменять диаграмму, просто редактируя текстовое описание. По сравнению с Draw.io создание диаграмм последовательностей в PlantUML существенно быстрее и проще.
@startuml
title Проведение платежа
participant UI as ui
participant Scheduler as scheduler
participant Rabbit as rabbit
participant PaymentService as payServ
participant YandexClient as ya
participant Database as db
== Создание платежа ==
ui -> payServ ++
payServ -> db ++
return paymentId
return paymentId
'это дополнительный промежуток между блоками
|||
== Создание задач на обработку платежей ==
scheduler -> payServ ++
payServ -> db ++
return unprocessed paymentIds
loop batch по 100 платежей на задачу
payServ -> rabbit : создание задач
end
deactivate payServ
== Проведение платежей ==
rabbit -> payServ ++
payServ -> db ++
db -> payServ : необработанные платежи
loop для каждого paymentId в задаче
payServ -> ya
ya -> payServ : yandexPaymentId
payServ -> db : сохранение проведенного платежа
end
deactivate db
deactivate payServ
|||
@enduml
- Определение участников (actors). В PlantUML вместо использования стандартного участника participant можно указать специфичные типы, например, database, что позволит более точно отобразить роль каждого компонента.
- Использование плейсхолдеров. Для упрощения процесса можно использовать плейсхолдеры и переменные, что позволяет избежать повторного указания одних и тех же элементов.
- Добавление заметок (notes). При необходимости добавить пояснения или уточнения, можно использовать команды note right или note left, что позволяет разместить дополнительную информацию рядом с основными элементами диаграммы.
Sequence-диаграммы имеют два ключевых ограничения: сложности с отображением ветвлений и перегруженность элементов. Ветвления, которые возникают при выполнении нескольких альтернативных действий, трудно визуализировать в рамках одной диаграммы, поэтому их лучше дополнять диаграммами Activity для наглядности. Перегруженность диаграмм, вызванная большим количеством участников и сообщений, можно уменьшить, разделив процесс на несколько диаграмм или добавив заметки и placeholder’ы для упрощения восприятия.
Activity Diagram
Диаграмма активности позволяет визуализировать алгоритмы и процессы, что особенно полезно при согласовании базовых алгоритмов с лидом или другими членами команды. Она помогает объяснить, как планируется писать код, и согласовать основные этапы разработки.
Инструмент поддерживает визуализацию сложных процессов, таких как параллельные ветви, циклы и блоки с заметками.
- Использование стандартных блоков: для создания диаграммы активности необходимо использовать стандартные блоки программирования, такие как условия, циклы и различные типы циклов.
- Добавление ветвлений и циклов: для отображения ветвлений и циклов можно комбинировать диаграммы активности с диаграммами последовательностей, что позволяет более гибко управлять логикой алгоритмов.
- Использование заметок: для пояснения отдельных блоков можно добавлять заметки с помощью команды note right или note left, что помогает лучше объяснить происходящие процессы.
- Активирование и деактивирование блоков: команды activate и deactivate позволяют управлять состоянием блоков, что особенно полезно для отображения начала и конца активности.
Итоги
В целом, я планирую создавать диаграммы преимущественно с помощью PlantUML, поскольку этот инструмент быстрее и проще в использовании. Но если мне будет необходимо быстро что-то согласовать, то я скорее выберу Draw.io, чтобы точно быть уверенным в том, что все поймут мою схему.
Если мне нужно объяснить что-то джуну, я, скорее всего, предоставлю ему исходный код напрямую и отправлю делать диаграмму в PlantUML. Кстати, стоит отметить, что исходный код легко передать ChatGPT для генерации диаграмм. Можно попросить ChatGPT создать диаграммы на основе миграций, сущностей или репозиториев, что значительно упрощает процесс документирования и визуализации базовых сервисов и классов. Но об этом я расскажу в следующий раз.
Резюмируя: PlantUML предпочтительнее и для быстрой и эффективной визуализации, а Draw.io может быть использован для более детализированных и согласованных диаграмм с более опытными коллегами. Используйте оба инструментов в зависимости от контекста и повышайте качество коммуникации и документирования в команде.
