Для сложных информационных систем бывает крайне сложно принять компромиссные решения с учетом ограниченных ресурсов. Одним из возможных способов решения является подход Architecture Description Log, который внедрен в крупных компаниях, таких как Google, Spotify и Microsoft. В этой статье мы рассмотрим основные положения ADL и обсудим, чем это может быть полезно для создания сбалансированной архитектуры в гибкой методологии разработки.

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

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

Запись ADL (Architecture Decision Record, далее ADR) может храниться непосредственно в git-репозитории, поскольку может быть представлена документом с простой разметкой (AsciiDoc, Markdown и др.). ADR могут версионироваться и связываться отношением зависимости и переопределения устаревшего документа. Для работы с ADR можно использовать этот набор инструментов командной строки, который позволяет создавать инициализировать каталог с ADR в репозитории проекта (adr init) и создавать новые ADR (adr new).

• Название содержит короткую фразу, описывающую архитектурные решения.

• Статус может быть:

  • Предлагается (рассматривается)

  • Принято (одобрено и готово к внедрению)

  • Заменено (заменено другим решением)

• Контекст объясняет, почему нам нужно принять решение. В нем также описаны альтернативы, а также плюсы и минусы.

• В решении описывается обоснование того, почему было принято конкретное решение. В нем больше внимания уделяется "почему", а не "как". Решение включает в себя набор альтернатив, аргументов и последствия принятия этой альтернативы.

• Раздел последствий содержит информацию об общем воздействии архитектурного решения. У каждого решения есть компромиссы и их нужно указать. Также если архитектурное решение предполагает декомпозицию (например, если описывается верхнеуровневая архитектура интеграции, а затем дорабатываются отдельные документы по технологиям и протоколам для взаимодействия внутренних систем).

Хороший ADR должен обладать следующими характеристиками:

• Рациональный: должны быть указаны причины выбора именно этой альтернативы, плюсы и минусы различных потенциальных вариантов, сравнение функций, обсуждение затрат и выгод и многое другое.

• Конкретика: каждый документ ADR должно содержать только одно принятое решение (например, выбор технологии разработки кроссплатформенных мобильных приложений).

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

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

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

Также важно обеспечить актуальность ADR, однако сделать это автоматически с использованием инструментов кодогенерации может быть сложно, так как этот документ не является техническим описанием (как, например, документация по API или иерархия классов, которая может быть создана на основе исходного кода), но скорее должен стать площадкой для дискуссий между разработчиками, архитекторами и бизнесом, в которой принимаются и фиксируются архитектурные решения.

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

• Шаблон ADR от Майкла Найгарда (простой и популярный)

• Шаблон ADR Джеффа Тайри и Арта Акермана (более сложный)

• Шаблон ADR для александрийского шаблона (простой с учетом специфики контекста)

• Шаблон ADR для бизнес-кейса (более ориентированный на MBA, с затратами, SWOT и большим количеством мнений)

• Шаблон ADR MADR

• Шаблон ADR с использованием Planguage (более ориентированный на обеспечение качества)

Также можно использовать специальные инструменты для навигации по набору ADR, например AdrViewer или AdrLog.

Полезный опыт внедрения ADR можно посмотреть в публикации Spotify, AWS, Redhat и Github.

В завершение рекомендую открытый урок в OTUS, на котором участники рассмотрят архитектурное свойство «Сопровождаемость» на примере соответствующих сервисов k8s: Pod, Deployment, ReplicaSet. Записаться можно на странице курса Software Architect.