Architecture Decision RecordПроцесс записей архитектурных решений в AWS
Запись архитектурного решения (ADR) — это документ, который описывает выбор, сделанный командой в отношении существенного аспекта программной архитектуры, которую она планирует создать. Каждая ADR описывает архитектурное решение, его контекст и последствия. У ADR есть состояния, а значит, они проходят жизненный цикл. Пример ADR см. в приложении.
Результатом процесса ADR является набор записей архитектурных решений. Этот набор образует журнал решений. Журнал решений даёт контекст проекта, а также подробную информацию о реализации и проектировании. Участники проекта просматривают заголовки каждой ADR, чтобы получить общее представление о контексте проекта. Они читают ADR, чтобы глубоко погрузиться в реализацию проекта и выбор проектных решений.
Когда команда принимает ADR, она становится неизменяемой. Если новые знания требуют другого решения, команда предлагает новую ADR. Когда команда принимает новую ADR, она заменяет предыдущую.
Область применения процесса ADR
Участникам проекта следует создавать ADR для каждого архитектурно значимого решения, влияющего на программный проект или продукт, в том числе для следующих (Richards and Ford 2020):
Структура (например, такие паттерны, как микросервисы)
Нефункциональные требования (безопасность, высокая доступность и отказоустойчивость)
Зависимости (связанность компонентов)
Интерфейсы (API и опубликованные контракты)
Методы построения (библиотеки, фреймворки, инструменты и процессы)
Функциональные и нефункциональные требования — наиболее распространённые входные данные процесса ADR.
Содержание ADR
Когда команда определяет потребность в ADR, один из участников начинает писать её на основе общего для проекта шаблона. (Примеры шаблонов см. в организации ADR на GitHub.) Шаблон упрощает создание ADR и гарантирует, что в ней отражена вся существенная информация. Как минимум каждая ADR должна определять контекст решения, само решение и последствия решения для проекта и его результатов. (Примеры этих разделов см. в приложении.) Одна из самых сильных сторон структуры ADR в том, что она сосредоточена на причине решения, а не на том, как команда его реализовала. Понимание того, почему команда приняла решение, облегчает его принятие другими участниками и не позволяет другим архитекторам, не участвовавшим в процессе принятия решения, отменить его в будущем.
Процесс принятия ADR
Любой участник команды может создать ADR, но команде следует определить, что такое владение ADR. Каждый автор, являющийся владельцем ADR, должен активно поддерживать и доводить до сведения других содержание ADR. Чтобы прояснить это владение, в последующих разделах настоящего руководства авторы ADR называются владельцами ADR. Другие участники команды всегда могут вносить вклад в ADR. Если содержание ADR изменяется до того, как команда её принимает, владелец должен одобрить эти изменения.
После того как команда определяет архитектурное решение и его владельца, в начале процесса владелец ADR представляет её в состоянии Proposed (предложена). ADR в состоянии «предложена» готовы к рассмотрению.
Затем владелец ADR запускает процесс рассмотрения ADR. Цель процесса рассмотрения — решить, примет ли команда ADR, определит, что её нужно доработать, или отклонит. ADR рассматривает проектная команда, включая владельца. Совещание по рассмотрению должно начинаться с выделенного времени на чтение ADR. В среднем достаточно 10–15 минут. За это время каждый участник команды читает документ и добавляет комментарии и вопросы, отмечая неясные темы. После этапа рассмотрения владелец ADR зачитывает и обсуждает с командой каждый комментарий.
Если команда находит пункты действий для улучшения ADR, состояние ADR остаётся Proposed. Владелец ADR формулирует действия и совместно с командой назначает исполнителя для каждого из них. Каждый участник команды может вносить вклад в пункты действий и закрывать их. Владелец ADR отвечает за повторное назначение процесса рассмотрения.
Команда также может решить отклонить ADR. В этом случае владелец ADR добавляет причину отклонения, чтобы предотвратить будущие обсуждения той же темы. Владелец меняет состояние ADR на Rejected (отклонена).
Если команда одобряет ADR, владелец добавляет метку времени, версию и список заинтересованных сторон. Затем владелец обновляет состояние на Accepted (принята).
ADR и создаваемый ими журнал решений отражают решения, принятые командой, и дают историю всех решений. По возможности команда использует ADR как справочный материал при проверках кода и архитектуры. Помимо проведения проверок кода, задач проектирования и задач реализации, участникам команды следует обращаться к ADR за стратегическими решениями по продукту.
В качестве хорошей практики каждое изменение программного обеспечения должно проходить рецензирование коллегами и требовать как минимум одного одобрения. Во время проверки кода рецензент может обнаружить изменения, нарушающие одну или несколько ADR. В этом случае рецензент просит автора изменения кода обновить код и делится ссылкой на ADR. Когда автор обновляет код, коллеги-рецензенты одобряют его, и он вливается в основную кодовую базу.
Процесс рассмотрения ADR
После того как команда принимает или отклоняет ADR, их следует рассматривать как неизменяемые документы. Для изменения существующей ADR необходимо создать новую ADR, организовать для неё процесс рассмотрения и утвердить её. Если команда одобряет новую ADR, владельцу следует изменить состояние старой ADR на Superseded (заменена).