Термин как код уже стал популярным в области инфраструктура как код за последние несколько лет. Явной тенденцией в этой области является растущая доступность инструментов, которые позволяют определять инфраструктуру с использованием языков программирования общего назначения, таких как TypeScript, Java и C#, вместо языков конфигурации, таких как YAML или JSON, — таких как AWS CDK или Pulumi.

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

О чем архитектура как код?

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

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

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

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

Однако все эти инструменты имеют некоторые недостатки (с точки зрения архитектуры как кода):

  • Они полагаются на языки конфигурации, а не на языки программирования общего назначения.
  • У них либо вообще нет концепции отделения архитектурной модели от диаграммы (как Mermaid и PlantUML), либо они смешивают моделирование и построение диаграмм (как Ilograph).

Отделение модели архитектуры от создания диаграмм с помощью Structurizr

Чтобы лучше понять два последних пункта, давайте рассмотрим еще один инструмент: Structurizr.

Позвольте мне выделить несколько моментов в фрагменте кода, показанном выше:

  • Он использует Java, а не язык конфигурации
  • Он четко отделяет определение архитектурной модели (имеется в виду: строительные блоки вашей системы и их отношения) от определения диаграмм на основе этой модели.
  • Он ничего не говорит о том, как отображаются эти диаграммы. Это связано с тем, что Structurizr, поставляемый с собственным движком рендеринга, может использоваться с различными движками рендеринга, включая Mermaid, PlantUML и Ilograph.

Работа со Structurizr обычно включает в себя 3 разных этапа:

1. Моделирование вашей архитектуры

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

2. Определение диаграмм на основе определенной модели

Отделение определения диаграмм от модели позволяет вам контролировать, какие элементы вашей модели относятся к диаграмме, без необходимости повторять определения элементов на диаграммах.

3. Визуализация диаграмм

После того, как вы определили свою модель и диаграммы, вы можете воспользоваться несколькими способами визуализации диаграмм:

Преимущества моделирования перед построением диаграмм

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

Создание нескольких согласованных представлений

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

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

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

Схемы рестайлинга

Второе самое полезное преимущество, которое вы получаете, — это возможность быстро и последовательно (пере-) стилизовать все ваши диаграммы:

Преимущества кодирования перед рисованием

Наконец, давайте подробнее рассмотрим типы вещей, которые можно использовать с помощью языков программирования общего назначения для создания архитектурных моделей и диаграмм — в отличие от решений на основе конфигурации, таких как Mermaid, PlantUML или Ilgraph, или классических инструментов рисования, таких как diagrams.net или Visio. .

Упрощенное управление версиями документации

В основном это применимо при сравнении решений на основе кода, таких как Structurizr, с классическими инструментами рисования, такими как диаграмма.net. Другие решения на основе конфигурации, такие как Mermaid, также частично используют это преимущество.

На следующих снимках экрана показана разница между git и…

  • Файл .drawio создается с помощью диаграмм.net после небольшого изменения макета.

  • Модель Structurizr после добавления документации по совершенно новому компоненту в системную архитектуру.

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

Взаимодействие между инструментами

При использовании языков программирования общего назначения обычно довольно легко добавить возможность взаимодействия с другим инструментом. Позволь мне привести пример. Допустим, вы создали архитектурную модель с помощью Structurizr, но хотите использовать Ilograph для визуализации диаграмм. Используя такие библиотеки, как ilograph-typescript, создание диаграмм Ilograph из вашей модели Structurizr может быть выполнено всего несколькими строками кода:

Зависимости компонентов последовательно отображаются на диаграмме и в коде.

Я просто проиллюстрирую этот момент картинкой:

Ваша документация с большей вероятностью будет обновляться

Посмотрим правде в глаза: большинству разработчиков нравится писать код больше, чем использовать Visio или другие инструменты для рисования, чтобы привести документацию в соответствие с изменяющейся кодовой базой. В результате многие документы по архитектуре устарели. Используя исходный код в качестве основы для документирования, вы можете включать обновления документации в процесс CI/CD.

Нашли эту статью полезной? Подпишитесь на меня (Christian Eder) на Medium и ознакомьтесь с моими статьями об Azure, AWS, Infrastructure as Code и IoT ниже! Не забудьте 👏 эту статью, чтобы поделиться ею!

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