Всем привет! Меня зовут Анатолий, я работаю ИТ‑архитектором в Сбере. Занимаюсь развитием направления клиентской лояльности. Сразу же отмечу, что в этой статье не идёт речь о фундаментально правильных решениях. Скорее, наоборот, речь идёт о решениях компромиссных.

В целом, зрелость архитектурной культуры организации можно оценивать соответствием неким условным уровням. Кратко их опишу.

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

Второй: каждый рисует и оформляет решения на своё усмотрение, диаграммы рисуют в чём угодно — MS Visio, PowerPaint, DrawIO, Mermaid, может быть, даже в MS Paint. Решение обсуждает и согласует группа сотрудников, собранная автором решения. Гораздо лучше, чем первый уровень, но эффективность и качество процесса невысоки: возможны ошибки; потери времени на поиск средства просмотра решения и на понимание, что хотел отразить автор; отсутствие согласований от нужных сотрудников.

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

Четвёртый: внедряется централизованное решение для разработки, согласования и фиксации архитектурного решения. Жизненный цикл и соблюдение основных правил разработки решения реализуются и контролируются автоматически. Все архитектурные решения фиксируются в репозитории. Это самый высокий уровень. При его достижении уже можно подключать LLM‑решения, ИИ‑агенты для разработки, контроля качества и предварительной оценки решений. 

Если в вашей компании уже живёт полноценная система для архитектурных решений в виде Aris, Sparx Enterprise Architect или их аналог, и она умеет всё, что нужно — описывать бизнес‑сценарии, собирать связанные с ними решения, показывать и согласовывать их с заказчиками, а потом аккуратно складывать в единый архитектурный репозиторий, — то тогда, скорее всего, эта статья не для вас. Вы и так всё это проходили.

А вот если такой системы нет или бюджет на неё пока не выделили, но потребность в наглядной архитектуре и порядке в ней уже назрела, то, возможно, мой опыт позволит вам быстрее и легче достичь «третьего» уровня и успешно его пройти.

Итак, проблематика...

При разработке ИТ‑решения часто нужно не просто набросать схему и согласовать её, а заложить базис для управления архитектурными решениями. Чтобы всё было единообразно, прозрачно, чтобы можно было переиспользовать и развивать. Для этого PlantUML с sequence‑диаграммами — настоящая находка. С их помощью можно быстро и наглядно показать последовательность взаимодействия компонентов, а заодно задать единую нотацию. Она со временем способна превратиться в рабочий архитектурный фундамент. Дальше покажу, как подступиться к этому инструменту и сразу получить отдачу.

Например, можно нарисовать красивую диаграмму компонентов в DrawIO, MSVisio или в любом другом редакторе диаграмм. Но при усложнении решения до 5–10 взаимодействующих друг с другом компонентов и количестве шагов в интеграциях между компонентами свыше 10 оказывается, что восприятие вашего решения аудиторией существенно ухудшается. Можно долго водить указателем по шагам, но слушатели очень быстро потеряют нить ваших рассуждений. Вот, например, такое абстрактное решение:

Что мы видим на этом изображении? Потратив прилично времени, устав от неудобства интерфейса и ограниченности функций DrawIO, мы получили запутанную и сложновоспринимаемую схему. Непонятно, откуда начинаются, и где заканчиваются сценарии. Непонятно, сколько их на схеме. Если прямой поток взаимодействия ещё можно худо‑бедно отследить по номерам, то поток возвращаемых результатов превращается в настоящее расследование. И пройдя по этому ребусу от начала до конца и обратно, мы забудем, что было вначале, и наверняка упустим важные моменты. И это только по одному сценарию, а их на диаграмме мне удалось насчитать целых пять.

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

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

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

В‑третьих, возрастает риск отказа в согласовании решения из‑за его непонятности.

Выход есть!

И тут нам на помощь приходит PlantUML и его sequence‑диаграммы. Почему мы выбрали PlantUML, а не Mermaid, C4-PlantUML или ArchiMate? Причин несколько:

• Mermaid остаётся предпочтительным выбором для быстрых набросков в документации и Markdown‑ориентированных рабочих процессов. Для использования Mermaid без доступа к интернету потребуется установка web‑приложения в сети организации.

• C4-PlantUML — это специализированная надстройка, которая расширяет PlantUML, но не заменяет его.

• ArchiMate — это отдельная нотация, которую чаще всего никто не знает.

• PlantUML является фундаментом, на котором строятся все эти решения, и именно он предоставляет максимальную гибкость, мощность и универсальность для визуализации сценариев любой сложности

• Так исторически сложилось. 

Мечта архитектора (или аналитика) на практике: описываете шаги решения коротким и ёмким синтаксисом PlantUML и сразу визуализируете через плагин для Confluence, прямо в VSCode, GIGAIDE или на любом из десятка сайтов. На обсуждении коллеги больше не смотрят на хаос из квадратиков, соединённых стрелками, — перед ними чёткая, последовательная история: кто с кем, когда и зачем взаимодействует. Никакой магии, только понятные сценарии использования решения.

Таким образом, набросав несложный код (ниже приведён код по умолчанию из плагина PlantUML для GIGAIDE), получаем понятное и удобное для восприятия отображение своих замечательных идей.

Пример такой абстрактной диаграммы:

Кроме того, при обсуждении сложных диаграмм у участников обсуждения возникают вопросы: «Что изменяется в предлагаемом решении? Что дорабатывается, что создаётся новое, что выводится?» На вышеприведённой диаграмме это непонятно. Можно ещё добавить необоснованно длинные, из‑за вытянутых надписей, стрелки, и общую угрюмо‑серую палитру. Конечно, можно переопределять цвет стрелок, переносить текст над ними добавлением ужасных «\n» (и при добавлении слова в начало такого текста весело двигать их между словами). И для каждого участника тоже можно указать свой цвет. Но всё это превращает формирование и изменение диаграммы в бесконечный малопроизводительный кошмар!

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

Для расцветки компонентов и интеграций применены стили. Их легко можно менять и расширять для соответствия стандартам визуализации решений, или просто переиспользовать!

Например, для новой автоматизированной системы или подсистемы определили стиль:

.sysN { BackGroundColor: #FFFF88; LineColor: #FF00FF; HorizontalAlignment: center; LineThickness: 2; RoundCorner: 5 } /* АС/ФП создается (New) */

Применив его к participant "Новая\n АС" as ASN <<sysN>>, получили такой весёлый прямоугольник:

Определив стиль для интеграции и функциональности:

.integD { LineColor: #CDA2BE; FontColor: #CDA2BE; HorizontalAlignment: left } /* интеграция выводится (Deleted) */
.funcO { BackGroundColor: #FFFF88; LineColor: #BD7000; HorizontalAlignment: center; LineThickness: 2; RoundCorner: 15; MaximumWidth: $funcWidth } /* функциональность создается в другом проекте (Other project) */

и применив эти стили:

rnote over ASO <<funcO>>: Функциональность, реализуемая в другом проекте
ASext ->> ASD <<integD>> : Выводимая интеграция

получаем существенно более информативную картину:

rnote over ASO : Функциональность\n, реализуемая в другом\n проекте
ASC -> ASO : Интеграция,\n реализуемая в другом\n проекте

превратились в человеческие

rnote over ASO <<funcO>>: Функциональность, реализуемая в другом проекте
ASC -> ASO <<integO>>: Интеграция, реализуемая в другом проекте

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

Итак, определив стили для основных задач и применив набор хитрых инструкций для форматирования, получаем стандарт и инструмент визуализации сценариев для нашей организации. Вот она, наша новая, удобная и разноцветная диаграмма!

Кратко об основных удобствах и преимуществах этого шаблона

Во‑первых, это соответствующие принятым в организации договоренностям форматы изображения объектов на диаграммах: компоненты, интеграции, функции, новые, дорабатываемые, выводимые, и тому подобное.

Во‑вторых, внятное и формализованное отображение шагов процесса, выполняемых внутри компонентов.

В третьих (и это просто бомба!), возможность автоматически переносить текст в наименованиях стрелок. Больше никаких «\n»!

В четвертых, более‑менее гибкий способ многоуровневой нумерации стрелок. 

Ну, и в‑пятых, в шаблоне собраны все необходимые для отражения различных нюансов решения элементы: комментарии, исключения, ссылки на подпроцессы.

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

К пяти бочкам мёда есть одна ложка дёгтя... Так и не разобрался, как сделать автоперенос в наименованиях компонентов. Комбинировал различные команды, но либо съезжал автоперенос в стрелках и функциях, либо дико интерпретировался «\n». Он всё‑таки иногда бывает нужен. Поэтому участников один раз прописываем с «\n», и потом для всего остального текста про них забываем.

Хочу высказаться ещё по одному аспекту sequence‑диаграмм PlantUML: отсутствию листания диаграммы с фиксацией компонентов в верхней (да и нижней!) части. Ладно бы плагины для встраивания PlantUML‑диаграмм в Сonfluence или какие‑нибудь другие wiki‑платформы! Но даже на https://www.plantuml.com/plantuml/uml/ и других сайтах такого нет! 

Таким образом, разработав длинную и теперь уже красивую диаграмму,в середине нашей презентации её благодарным слушателям мы вдруг понимаем, что запутались, откуда и куда ведёт нас шаг номер 3.1.5. Сами запутались, и аудиторию уже давно и надёжно запутали.

Я, признаюсь, был полон претензий к авторам стандарта и инструментов для рендеринга. Как можно было такую плюху пропустить? Даже Excel умеет фиксировать несколько верхних строк!

Даже подумывал скачать исходники какого‑нибудь open‑source‑плагина и эту досадную недоработку исправить. Хотя бы для себя. Но, тщательно поразмыслив, понял, что не могу придумать адекватного способа фиксировать эти заголовки. Для одинокой страницы с нашей диаграммой — нет вопросов. Фиксируешь сверху (и снизу) наименования компонентов и участников, масштабируешь вместе с диаграммой — всё прекрасно. А если твоя диаграмма вложена в два других пролистываемых объекта? Пролистывание на пролистывание — уже совсем сложно получается. Наверное, можно что‑то придумать, всплывающие прозрачные подсказки, но при передаче диаграммы кому‑то внешнему, лишённому нашего кастомизированного средства визуализации, она становится нечитаемой.

Нужно эффективное, универсальное платформонезависимое(!), переносимое решение. Желательно — такое же красивое и цветное, как вся остальная наша диаграмма.

И этот путь нашёлся! 

Немного похимичив с Excel, удалось сделать простейшую формочку UML Seq — заголовки для АС v006.xlsx. Закинув в неё нашу сформированную диаграмму, мы получаем текстовый блок промежуточных заголовков и вставляем их в психологически и дизайнерски оправданные места диаграммы.

Этот инструмент даже проверит, соединён ли описанный участник стрелками с другими, и если нет, то не будет его добавлять в строку заголовков. Для последней функциональности есть суровое требование: стрелки в диаграмме должны быть отделены пробелами. То есть, для выражения вида «A → B» Excel поймёт, что A и B используются, а для «A→B» не поймёт... Так и не смог победить этот момент формулами в одиннадцатом Excel. 

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

'Клиент
Actor "Клиент или \n сотрудник" as user <<sysU>>
box "Группа АС N 1" #EDF8E3
'исп.АСparticipant "Используемая\n АС" as ASU <<sysU>>
participant "Дорабатываемая\n АС" as ASC <<sysC>>
'нов.АСparticipant "Новая\n АС" as ASN <<sysN>>
participant "АС\n создаваемая\n в другом\n проекте" as ASO <<sysO>>
'другой\n проект\n дорабатываемая\n АСparticipant "АС\n дорабатываемая\n в другом\n проекте" as ASChO <<sysChO>>

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

И, в итоге, мы получаем замечательную ненавязчивую строчку с названиями, какая линия что у нас означает.

Если в вашей организации нет ограничений на использование внешнего кода, то мы с нейронкой навайбкодили seq_add_head.html, который выполняет точно такую же функцию, только быстрее и удобнее. Копируете текст сформированной sequence‑диаграммы в верхнее поле, нажимаете кнопку «Добавить промежуточные заголовки», затем «Скопировать дополненный заголовками код», и получаете в буфере вашу диаграмму уже с заголовками. Кроме того, перед вставкой новых заголовков умный HTML удалит старые заголовки, если такие были.

Подытожим

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

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

Копируйте код шаблона диаграммы PlantUMLTemplate.uml, копируйте код seq_add_head.html или скачивайте UML Seq — заголовки для АС v006.xlsx и творите!