Если есть желание погрузиться в историю создания проекта, то лучше начать с этой, этой и этой статьи. Но это не обязательно. Инструмент серьезно трансформировался. Статья будет давать информацию “с чистого листа”.

Что такое код архитектуры? 

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

Но если писать программы кодом естественно, описывать инфраструктуру уже привычно, то похвастаться опытом описания архитектуры кодом может далеко не каждый. Хотя такие решения есть. Пожалуй, самый известным из них является PlantUML. Он позволяет создавать диаграммы из текста.

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml

Результат:

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

Вероятно, может возникнуть вопрос - А зачем это делать кодом? Чем не удовлетворяет, например, draw.io? В нем тоже есть много чего. Но при этом не нужно учить специальный язык. Мы так делали и у нас все получалось много раз!

Вопрос справедливый. Без осознания ценности подхода, нет смысла двигаться дальше. Одна из ключевых ценностей заключается в возможности командной разработки артефактов с использованием систем управления версиями (gitlab, bitbucket, github и пр.) Артефакты могут параллельно развиваться членами команды и объединяться аналогично привычному коду приложения.

Вторая, очень важная ценность - автогенерация. Современные инструменты должны уметь встраиваться в DevOps. Язык описания архитектуры хорошо для этого подходит. Появляется возможность генерировать артефакты автоматически. Например, трейся запросы между микросервисами создавать диаграммы последовательностей и взаимодействий. Врядли здесь поможет draw.io…

Третья - связывание кода. Предоставляется возможность переиспользовать артефакты. Аналогично подключению библиотек при программировании.

Четвертая, моя самая любимая - шаблонизация. Имея под рукой код, вы можете создавать собственные шаблоны. Абстракции над базовым языком. Что может существенно облегчить именно вашу, специфическую, деятельность по описанию.

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

Здесь можно было бы закругляться. И так все понятно. Бери PlantUML да делай. Но… не все так радужно. Давайте поговорим о проблемах.

Проблемы с кодом архитектуры

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

2. Код архитектуры, как любой другой код, должен быть читабельным. Влияет на это как синтаксис языка, так и тот, кто его пишет. Код описывающий тяжелые диаграммы в PlantUML с трудом можно назвать читабельным. Для его понимания необходима параллельная визуализация, навигация, подсветка синтаксиса, автоформатирование и желательно линтер. То есть, работа с кодом архитектуры должна быть обеспечена поддержкой IDE.

3. Создание файлов с описанием архитектуры, не решает вопроса навигации в них. Да, PlantUML поддерживает ссылки, но все мы знаем, что одно неловкое движение мышкой в дереве файлов может тут же “побить” все ссылки в проекте. Т.е. нам нужен, ко всему прочему, контроль консистентности нашей архитектуры. А в идеале - подсистема каталогизации.

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

Наличие этих проблем отворачивает потенциальных пользователей от технологии.

DocHub

DocHub устраняет блокирующие факторы входа в технологию описания архитектуры кодом. Для этого у него на борту:

1. Поддержка PlantUML. Все то, что умеет он, умеет и DocHub;

2. Помимо PlantUML поддерживаются Markdown и Swagger;

3. Собственный, облегченный язык описания архитектуры;

4. Портал документации;

5. Плагин для intellij IDEA.

Подробно познакомиться с функционалом можно тут. Не вижу смысла в статье повторять мануал. Лучше я покажу как легко и быстро можно начать работать с инструментом. Уже в примере мы увидим как решаются выше обозначенные проблемы.

Настройка среды

Здесь все предельно просто. Если у вас уже установлены продукты intellij IDEA, то вам достаточно в маркете плагинов найти DocHub и установить его. Если нет, то рекомендую к установке intellij IDEA Community Edition.

Инициализация проекта

После установки плагина вы тут же можете приступить к описанию архитектуры. Справа вы найдете вкладку DocHub. Клик на ней вызовет панель представления архитектуры.

Так как проект еще не инициализирован, плагин предложит вам два варианта: “Создать пустой файл” или “Создать пример”. Для наглядности выберите “Создать пример”. В корне проекта будет создан файл “dochub.yaml”. Результат его рендеринга вы увидите на панели DocHub.

Поздравляю! Вы описали свою первую архитектуру. Ну почти…

В файле “dochub.yaml” вы найдете исходный код архитектуры с подробными комментариями. Экспериментируйте с его модификацией и наблюдайте изменения в панели визуализации. Напомню, что подробный манул тут. 

Обзор функционала плагина

Очевидно, что плагин умеет рендерить архитектуру. Изменения в коде тут же приводят к отражению изменений на панели визуализации.

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

Реализована навигация как внутри самого кода архитектуры, так и между визуализацией и кодом.

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

Так как же DocHub помогает решать проблемы?

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

  system.gateway:             # Иерархия компонентов определяется структурой их идентификаторов
    title: API шлюз
    entity: component
    links:
      - id: system.backend
        title: Бизнес API
        direction: <-->
        contract: https://editor.swagger.io/  # Можно указать контракт взаимодействия внешней ссылкой
      - id: system.auth
        title: Auth API
        direction: <-->
        contract: example                     # Или, контракт можно указывать идентификатором документа
    technologies:             # Технологии используемые в компоненте
      - HTTP
      - OAuth

Согласитесь, что она читается достаточно просто.

Наличие навигации по коду дает все профиты доступные развитым языкам программирования. Подсветка синтаксиса тут же. Квикфиксы и валидация структур сильно облегчают работу с кодом.

Также очевидно, что теперь всю необходимую информацию вы найдете в одном месте - в панели DocHub. Контроль косистентности плагин осуществляет налету.

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

Заключение

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

Думаю, для многих будет важным узнать, что проект является OpenSource. Как портал DocHub, так и плагин.