| November 15, 2023
Документирование архитектурных решений помогает нынешним и будущим участникам разработки обрести понимание причин, лежащих в основе принятых решений в ходе разработки. Одним из популярных подходов документирования архитектурных решений является Architecture Decision Records.
ADR 101
Что это
Architecture Decision Record или ADR - это документ, который содержит описание архитектурного решения, включая контекст того, как и почему решение было принято и какие последствия это за собой влечёт.
ADR-ы в основном создаются тогда, когда необходимо принять значительное архитектурное решение, такое как выбор новой технологии, фреймворка или шаблона проектирования, или когда необходимо найти компромисс между архитектурными целями, такими как производительность, масштабируемость, поддерживаемость и т.д.
ADR-ы так же могут быть полезны при документировании уже принятых решений. И наконец, ADR-ы позволяют убедиться в том, что разработка соответствует IT стратегии организации и помогает в достижении целей организации.
Формат
Формат ADR-записи довольно простой. Документ содержит небольшой список элементов, предлагаемых к заполнению:
- Название содержит краткое описание изменения архитектуры; является названием самой ADR-записи
- Дата создания ADR-записи
- Статус ADR-записи. Он может быть разный и специфичной для компании. Один из популярных подходов это создавать ADR-записи в статусе “Черновик”, и, затем, после обсуждения и принятия какого-то решения, менять его на “Принято” или “Отклонено”.
- Контекст описывает проблему, которая и привела к созданию данного изменения архитектуры. Здесь же приводится дополнительная информация для того, чтобы дать больше информации о контексте проблемы.
- Решение содержит обоснование того, почему было принято конкретное решение. Тут больше уделяется внимание именно “почему”, а не “как”.
- Последствия содержит информацию об общем воздействии принятого архитектурного решения на систему и организацию.
Вот пример архитектурной записи:
# 47. Использование ArchUnit в качестве фитнес-функции для проверки архитектуры java-микросервисов
Дата создания: 2023-11-15
## Статус
Принято
## Контекст
В компании принят `package-by-layer` подход для всех java-микросервисов. Далеко не все разработчики чётко следуют рекомендуемому подходу. Многие о нём попросту не осведомлены или не умеют применять. Как итог - отсутствует общий подход в плане структурирования элементов кода в java-микросервисах.
## Решение
Для организации автоматического контроля следованию рекомендуемому подходу построения java-микросервисов, используется библиотека для тестирования архитектуры java приложений - ArchUnit (https://www.archunit.org). Команда архитекторов решений создаёт и поддерживает автоматизированную проверку, добавляемую в каждый микросервис, каждой команды.
## Последствия
Следующие последствия возможны в результате применения подхода:
* временное замедление скорости разработки продуктов. Связано это с тем, что автоматизированная проверка будет пресекать попытки нарушить рекомендуемый подход и не пропустить разработчика дальше по жизненному циклу фичи до исправления найденной архитектурной проблемы. Потребуется какое-то время до того, как все разработчики перейдут на новый подход и освоятся с ним.
* возможны конфликты при внедрении автоматической проверки в микросервисные проекты
* недовольство разработчиков ("закруичвают гайки")
Шаблонов ADR-записей существует множество. Формат легко меняется и адаптируется под нужды конкретной организации. Однако, существует перечень наиболее популярных шаблонов. Его можно найти здесь.
Когда использовать
Использовать ADR’ы на всех проектах - пустая трата времени и сил.
Если речь идёт про небольшие pet-проекты, то они там не нужны. Лучше потратить временные ресурсы на разработку очередной фичи.
Если речь идёт про стартап-проекты, то и там они не нужны. Ведь в стартапе всё нацелено на как можно более скорое получение рабочего MVP. Зачастую слово “документирование” в них моветон.
А вот для больших проектов с длительной историей, ADR’ы могут быть крайне полезны. Для документации архитектурного видения и отслеживания его изменения.
Тулинг
Для того, чтобы начать использовать ADR никаких специальных инструментов не нужно. Достаточно обычного текстового редактора или пространства в Confluence. Однако, существуют и специальные инструменты, которые облегчат создание записей принятых архитектурных решений. Одним из таких инструментов является ADR Tools.
ADR Tools - это консольная утилита, а если быть точным - набор shell скриптов, которые позволяют легко и быстро создавать ADR’ы.
Для того, чтобы установить утилиту на macOS достаточно воспользоваться популярным менеджером пакетов Homebrew (инструкции для установки на остальных операционных системах можно найти здесь):
brew install adr-tools
Прежде чем начать создавать собственные ADR’ы, необходимо проинициализировать директорию, в которой эти записи будут храниться. Делается это следующей командой в терминале, выполненной из корневой директории Вашего проекта:
adr init [путь к директории с ADR'ами. Например: doc/architecture/decisions]
В результате выполнения этой команды, утилита создаст необходимые поддиректории, а так же создать первую ADR-запись, имеющую начальный номер 001.
Чтобы добавить новую ADR-запись, достаточно выполнить следующую команду:
adr new [название записи]
Например:
adr new Use ADR as the way to document architecture
Она создаст новую ADR, имеющую название - Use ADR as the way to document architecture, а также следующий порядковый номер.
В результате моих экспериментов, у меня получилось что-то подобное:
.
└── doc
└── architecture
└── decisions
├── 0001-record-architecture-decisions.md
└── 0002-use-adr-as-the-way-to-document-architecture.md
Как и с любыми консольными утилитами, если потребуется помощь, справочную информацию можно получить, используя следующую команду:
adr help
Полученные ADR-записи сохраняются в формате markdown, что делает их превосходными кандидатами для добавления в систему контроля версий (VCS).
Выводы
ADR - это отличный способ получить структурированное описание различных архитектурных ограничений и правил, а так же сохранить контекст обсуждений принятых решений. Почти всегда у новых людей, пришедших на проект, возникают различные вопросы “как и почему делается так, как делается” и ADR’ы могут помочь объяснить новым членам команды по каким причинам были приняты те или иные решения.