tekBlueprint

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

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

В этом контексте появляется концепция Architecture as Code (AasC), которая предлагает использовать инструменты разработки программного обеспечения для управления архитектурными моделями. Это позволяет автоматизировать процесс создания и поддержания документации архитектуры, обеспечивая её актуальность и согласованность с реальной системой.

Архитектура как код (Architecture as Code)

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

На мой взгляд, можно выделить следующие преимущества Architecture as Code:

1. Структурированность – шаблоны документов, схем, моделей, подходов описания определены в едином стиле и понятны всем участникам процесса.
2. Согласованность – архитектурные модели всегда актуальны и согласованы с реальной системой благодаря интеграции с процессом разработки. Изменения в проектную документацию вносятся непосредственно и обязательно перед изменениями в разрабатываемом решении.
3. История изменений – использование систем контроля версий позволяет отслеживать изменения в архитектуре, что полезно для анализа изменений, происходивших на протяжении всего жизненного цикла разработки.
4. Доступность – архитекторы, аналитики и разработчики видят актуальную картину мира и работают с одними и теми же артефактами.
5. Интеграция – легко интегрировать с CI/CD-пайплайнами для автоматического обновления документации.

Инструменты для организации подхода AasC

Из основных инструментов, которые приходилось использовать, хочется выделить следующие:

1. PlantUML – это инструмент для создания UML-диаграмм с использованием простого текстового языка. Он поддерживает широкий спектр типов диаграмм, включая последовательные, компонентные и классовые.
2. AsciiDoc – это текстовый формат документации с поддержкой разметки, который может быть использован для создания технической документации, включая диаграммы.
3. Markdown – легкий в использовании формат разметки, идеально подходящий для быстрого создания документации.
4. Mermaid – это JavaScript-библиотека для рендеринга диаграмм и потоковых схем из простого текстового описания. Для нестандартных диаграмм.

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

Info

Более подробно об этом в отдельной статье про инструменты.

Structurizr

При всем этом всегда была одна проблема: приходилось выстраивать структуру документации вручную, с правилами генерации выходной документации и их публикацией. С одной стороны, это делается один раз под проект, но с другой стороны это требует времени и усилий. В качестве альтернативы сейчас возможно использовать Structurizr – это инструмент, который позволяет автоматизировать процесс описания архитектуры (документация, ADR, диаграммы, связи и т. д.).

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

Важный момент, о котором стоит помнить: генерация диаграмм выполняется через внешние сервисы. По этой причине необходимо разворачивать дополнительные сервисы внутри организации, т. к. отправка конфиденциальных данных по проекту на внешние сервисы нарушает NDA. Для отрисовки диаграмм без использования внешних сервисов реализовывал небольшой плагин Structurizr: Diagrams Plugin, позволяющий встраивать сгенерированные в оффлайне диаграммы как embedded изображения.