Введение в ADR с примерами, шаблонами и инструментами управления

Что такое отчеты об архитектурных решениях (ADR)

Записи архитектурных решений (ADR) документируют важные архитектурные решения, а также их контекст и последствия. Впервые они были представлены Майклом Найгардом в сообщении в блоге 2011 года.

ADR обычно состоит из короткого текстового файла, описывающего конкретное архитектурное решение. Вы можете написать их в виде простого текста, формата AsciiDoc/Markdown или использовать шаблон вики-страницы.

Преимущества использования ADR

Давайте рассмотрим некоторые из основных преимуществ использования ADR:

  • Они фиксируют важную информацию о программном обеспечении, которую можно просмотреть в любое время.
  • Они могут действовать как эффективное средство документирования архитектуры программного обеспечения. В ADR подчеркивается, почему было принято то или иное решение. В нем также описывается анализ компромиссов, например выбор производительности вместо масштабируемости.
  • Если разработчики хотят понять, почему для данного проекта была выбрана та или иная технология, они могут найти объяснение в ADR. Это снижает внутренние споры. У разработчиков есть критическое мышление, поэтому очень важно дать им понять, почему. Это приводит к большему доверию внутри команд.
  • Они помогают новым членам команды ознакомиться с архитектурным мышлением. Новички поймут, какие аспекты играют наиболее значимую роль в инфраструктуре. Они получат представление о том, что было сделано в прошлом.
  • Если кто-то захочет предложить новую технологию, может оказаться, что тема уже обсуждалась и отвергнута. Причина в ДОПОГ. Таким образом, они могут инвестировать свое время в поиск нового решения.
  • Обеспечьте прозрачность внутри и снаружи команд. Все, кто интересуется этой темой, могут прочитать о процессе принятия решения. Таким образом, разные группы могут учиться друг у друга.

Структура ADR

ADR должны быть краткими и простыми.

Заголовок

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

Пример:

Язык программирования и фреймворк для нашего интерфейса.

Положение дел

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

  • Предложено (на рассмотрении)
  • Принято (одобрено и готово к реализации)
  • Заменено (заменено другим решением)

Контекст

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

Пример:

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

Решение

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

Пример (Это просто иллюстрация технического решения, ничего страшного, если вы с ним не согласны):

Мы будем использовать Flutter в качестве внешнего интерфейса.

Мы рассмотрели следующие рамки:

  • Флаттер
  • Реагировать на родной

Аргумент

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

React Native — большинство компонентов нам приходится реализовывать самим. Документация не очень подробная. Общая производительность не так хороша, как у Flutter.

Последствия

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

Пример:

У него есть кривая обучения: разработчики должны изучить язык программирования Dart, чтобы использовать фреймворк Flutter.

Когда писать ADR

Вы можете спросить себя: должен ли я всегда писать ADR? Не обязательно, но вот несколько моментов, которые помогут вам решить, стоит ли создавать ADR:

  • Вы слышите, как люди постоянно задают одни и те же вопросы: Почему было принято именно это решение? Почему архитекторы выбрали именно эту технологию, а не эту? У текущей реализации есть компромиссы, такие как более низкая производительность, так почему же они выбрали именно такую ​​архитектуру?
  • Вы хотите предложить изменение, которое повлияет на все программное обеспечение? Это подходящий способ начать дискуссию, в которой можно рассмотреть все за и против.

Управление ADR

Хранилище

Вы можете хранить ADR в репозитории Git в отдельной папке ADR. Однако не у всех может быть доступ к Git, например, у бизнес-аналитиков, владельцев продуктов и т. д. Поэтому это не самый оптимальный выбор. Самый простой способ — хранить ADR на общей вики-странице, где каждый может их увидеть.

Шаблоны

Если вы не знаете, с чего начать, не волнуйтесь, потому что уже существует множество шаблонов ADR. Наиболее широко используется Майкл Найгард:



architecture-decision-record/index.md на главной странице · joelparkerhenderson/architecture-decision-record
Это шаблон из документа «Документирование архитектурных решений — Майкл Найгард. Вы можете использовать adr-tools для управления ADR…github.com»



Посмотрите эту коллекцию на GitHub, чтобы узнать больше идей и стилей.

Инструменты

Существуют различные инструменты, которые помогут вам отслеживать ваши ADR. В этом вам поможет удобный и легкий инструмент: https://github.com/mrwilson/adr-viewer.

Этот инструмент на основе Python показывает ADR на локальном веб-сервере или в виде сгенерированного статического содержимого.

Полную демонстрацию можно найти здесь: https://mrwilson.github.io/adr-viewer/index.html

Если у вас уже есть ADR, рассмотрите возможность создания журнала. Инструмент Adr-Log формирует журнал архитектурных решений из ADRS:

Для работы с журналами ADR я рекомендую инструмент командной строки под названием Adr-tools. Он запускает команды для создания ADR на основе шаблона, например, такого как этот:

Последние мысли

Поздравляем! Вы изучили принципы ADR. Теперь вы знаете, почему, когда и как их использовать. Я также перечислил несколько полезных инструментов для управления ADR.

Я надеюсь, что вы узнали что-то новое сегодня. Спасибо за чтение, и увидимся в следующий раз!