Привет! На связи Кнышенко Марина, системный аналитик Рунити. В этой статье мы попробуем сделать из UML универсальное средство общения, чтобы отрисованные диаграммы помогали наладить диалог между командой и не валялись в архиве в качестве средства устрашения. Статья будет интересна системным аналитикам, которые ищут универсальные инструменты для работы и хотят настроить коннект с командой. 

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

Навигация по тесту:

• Краткий экскурс в UML

• Типы диаграмм и рабочие кейсы

• Диаграмма прецедентов. Кто делает? Что делает?

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

• Диаграмма классов

• Диаграмма последовательности

• Разговорный клуб: как сделать UML-диаграммы понятными

• Заключение

Краткий экскурс в UML

UML (Unified Modeling Language) — это графический язык описания программных систем. С его помощью можно:

• структурировать и визуализировать сложную систему;

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

• прогнозировать несовершенства и ошибки системы на этапе проектирования.

О необходимости использования подхода можно поспорить, но плюсы UML всё же намекают на актуальность языка — он поддерживается большинством инструментов (от визуальных редакторов до генераторов кода), автоматизируется и позволяет на раннем этапе увидеть архитектурные конфликты. Особенно хорошо UML подходит для выражения двух мыслей: какой должна быть новая система и какие изменения нужно внести в существующую систему.

Типы диаграмм и рабочие кейсы

«Переводчиком» между языком моделирования и пользователями выступают диаграммы, созданные с помощью символов UML. Глобально все их можно разделить на 2 типа: структурные и поведенческие. Первые визуализируют систему, а вторые — отражают процесс работы. В свою очередь эти типы разветвляются на более мелкие виды диаграмм, в зависимости от задачи, которую нужно решить — на примере разберем, какой тип выбрать и как правильно построить логику.

Задача для примера: предоставить клиенту возможность оплатить заказ при помощи системы быстрых платежей.

Рассмотрим четыре диаграммы, наиболее подходящие для решения этой задачи:

1. Диаграмма прецедентов.

2. Диаграмма компонентов.

3. Диаграмма классов.

4. Диаграмма последовательности.

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

Диаграмма прецедентов. Кто делает? Что делает?

Отправная точка описания любой новой функции или доработки существующей системы. Эта диаграмма показывает, какие действия совершают пользователи и внешние системы. Основные элементы:

• Акторы — действующие лица. Обозначаются человечками.

• Прецеденты — действия, которые будут совершать акторы. Обозначаются овалами.

• Связи между ними — обозначается простой линией.

Попробуем нарисовать диаграмму прецедентов для нашей задачи.

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

На рисунке 2 показано, что в оплате СБП участвует Биллинг, который в какой-то момент сам начинает оплачивать заказы через СБП деньгами компании. Кошмар любого интернет-магазина и радость клиентов.

Совет: при определении актора задайте себе вопрос «Кто инициирует действие?». Сервисы вашей системы, как и люди, могут быть акторами, если, например, запускают процесс по расписанию: главное помните — кто начал, тот и актор.

На рисунке 3 Биллинг по своим настройкам cron сам понимает, когда ему выгружать данные, поэтому тоже может являться актором.

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

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

В UML компоненты обозначаются прямоугольниками, интерфейсы — кругами. Иногда добавляют акторов (например, пользователей или внешние системы), чтобы показать, кто инициирует взаимодействие.

Вернемся к рабочему кейсу: внедрение оплаты через СБП. Для этого понадобится минимум четыре компонента:

• Внешняя платежная система (например, ЮKassa или Paymaster) — через нее будет проходить оплата по СБП. Во избежание обвинения в рекламе предоставим менеджерам решать с кем выгоднее заключить контракт и на диаграмме компонентов будем называть этот модуль просто «Платежная система».

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

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

• Платежный модуль, который будет интегрироваться с внешней системой и переводить ответы в формат, понятный биллингу.

Мы определили четыре компонента: личный кабинет, биллинг, платежный модуль, внешняя платежная система. Почему нельзя подключить платежную систему напрямую к биллингу? Теоретически можно, но на практике — нет. Биллинг, особенно если ему больше пяти лет, — это археологический памятник с многослойной логикой и непредсказуемыми побочными эффектами. Лучше изолировать его от внешних API с помощью прослойки — платежного модуля. Это снизит риски и облегчит поддержку.

Теперь подумаем, как эти компоненты будут взаимодействовать друг с другом и с заинтересованными людьми. Компоненты взаимодействуют через API (между модулями) и веб-интерфейсы (с пользователями). Для наглядности на диаграмме удобно цветом отделить внешние системы (например, фиолетовым) от внутренних (синим) — чтобы сразу видеть границы ответственности.

Ошибки, которые часто встречаются:

Компонент ≠ интерфейс. Личный кабинет — это полноценное приложение со своей логикой, а часто и с разделением на frontend и backend. Его нельзя изображать как «кружочек-интерфейс» (см. рис. 5).

Прямой доступ в хранилище. Если на диаграмме видно, что пользователь напрямую взаимодействует с биллингом — это повод остановиться и пересобрать модель. Даже если на уровне кода всё через API, визуально это создает неверное представление о структуре и границах модулей (см. рис. 6).

Диаграмма классов. Какие сущности затрагиваем?

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

Класс в объектно-ориентированном проектировании — это шаблон (или модель) для создания объектов определенного типа. Можно сравнить его с выкройкой, по которой потом «шьются» платья-объекты — товары, счета, платежи и так далее. 

«Услуга», «Товар», «Счет» – всё это примеры классов, по которым в процессе коммерческой деятельности накапливается множество объектов. В нашем примере логично ввести класс «Платеж». У него могут быть следующие атрибуты: 

• amount — сумма;

• timestamp — время проведения;

• internalId — внутренний идентификатор;

• externalId — ID, полученный от платежной системы.

На диаграммах класс рисуют в виде прямоугольника с названием класса и списком атрибутов. Ниже — пример диаграммы, описывающей один класс Платеж с ключевыми свойствами (Рис 7).

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

Золотое правило звучит так: «Сколько прецедентов, столько и диаграмм последовательности». Это упрощает восприятие логики процессов и позволяет избежать избыточной сложности.

На диаграмме последовательности отображаются участники взаимодействия и порядок их действий. Нарисуем диаграмму последовательности для прецедента «Оплата заказа через СБП».

Ключевые элементы диаграммы: 

• Линии жизни обозначают участников (системы или пользователей). Пользователь может быть представлен в виде пиктограммы или прямоугольника с пунктирной линией.

• Сообщения отображаются стрелками: направление показывает, кто инициирует действие, подписи к стрелкам — содержание запроса или ответа.

Рекомендации по созданию диаграмм последовательности:

• Разделяйте успешные и альтернативные сценарии. Основной путь и возможные ошибки удобнее отображать на отдельных диаграммах.

• Фокусируйтесь на актуальном процессе. В диаграмме стоит отражать только те шаги, которые непосредственно связаны с текущей задачей. Например, выбор товара и формирование заказа можно опустить, если цель — описать процесс выбора способа оплаты.
  Дополняйте диаграмму текстовым описанием. Это поможет быстрее разобраться в логике взаимодействия.

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

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

На самом деле — где угодно. Главное, чтобы диаграмму можно было понять, версионировать и обновлять по мере развития проекта. Конкретный инструмент выбирается по вкусу команды: кому-то важен визуальный редактор, кому-то — текстовое описание в коде.

Вот несколько популярных вариантов: 

• draw.io — бесплатный, визуальный, простой в освоении. Поддерживает экспорт, интеграцию с Confluence. Один из самых популярных инструментов для быстрых и понятных схем.

• Visual Paradigm — мощный инструмент с широкими возможностями моделирования, но с ощутимым ценником. Подходит, если UML в команде — не разовая история.

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

Разговорный клуб: как сделать UML-диаграммы понятными (не только себе)

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

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

• Говорящие названия. Подписывайте элементы диаграммы так, чтобы их поняла и другие участники команды: «Сервис авторизации», «Клиент», «Мобильное приложение клиента». Не забываем расшифровывать и значение стрелок;

• Думайте о зрителе. Задавайте себе простой вопрос: кто будет это читать, и зачем? — и на основе этого решайте, что показывать, а что опустить.

• Тестируйте диаграмму на коллегах. Покажите диаграмму человеку, который не участвовал в разработке, и попросите рассказать, что он из неё понял. Отличный способ выявить неочевидные места.

Заключение

Изучение любого языка начинается с основ. Только что мы научились говорить на UML «Спасибо», «Пожалуйста», «Меня зовут Вася». Можно смело брать путевку и ехать в аэропорт, то есть начинать писать техническое задание в отдел разработки.

Освоив базовые диаграммы — компоненты, классы, последовательности — вы уже можете начинать писать понятные ТЗ, проводить ревью архитектуры и договариваться с разработкой без лишних слов. А дальше — будет проще. Творите красоту и не забывайте — главное, чтобы ее поняли ваши коллеги.

А вы используете UML в работе? Какие диаграммы помогли вам лучше всего объяснить архитектуру коллегам или заказчику? Задавайте вопросы и делитесь своими кейсами в комментариях — обсудим подходы, которые реально работают.