Шаблон записи решения от arc42

1. Введение и цели

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

1.1 Обзор требований

Содержание

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

Мотивация

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

Форма

Краткое текстовое описание, возможно, в табличном формате вариантов использования. Если документы с требованиями существуют, этот обзор должен ссылаться на них.

Делайте эти выдержки как можно короче. Соблюдайте баланс между читаемостью этого документа и возможной избыточностью по отношению к документам с требованиями.

1.2 Цели качества

Содержание

Три (максимум пять) главных целей качества для архитектуры, достижение которых наиболее важно для основных заинтересованных сторон. Мы действительно имеем в виду цели качества для архитектуры. Не путайте их с целями проекта. Они не обязательно совпадают. Стандарт ISO 25010 даёт хороший обзор потенциально интересных тем.

Мотивация

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

Форма

Таблица с самыми важными целями качества и конкретными сценариями, упорядоченными по приоритетам.

1.3 Заинтересованные стороны

Содержание

Явный обзор заинтересованных сторон системы, то есть всех лиц, ролей или организаций, которые

должны знать архитектуру
должны быть убеждены в архитектуре
должны работать с архитектурой или кодом
нуждаются в документации архитектуры для своей работы
должны принимать решения о системе или её разработке

Мотивация

Вы должны знать все стороны, вовлечённые в разработку системы или затронутые системой. Иначе вы можете получить неприятные сюрпризы позже в процессе разработки. Эти заинтересованные стороны определяют объём и уровень детализации вашей работы и её результатов.

Форма

Таблица с названиями ролей, именами людей и их ожиданиями в отношении архитектуры и её документации.

2. Ограничения

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

Содержание

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

Мотивация

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

Форма

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

3. Контекст и границы

Отделяет вашу систему от её (внешних) партнёров по взаимодействию (соседних систем и пользователей). Определяет внешние интерфейсы. Показывается с точки зрения бизнеса/предметной области (всегда) или с технической точки зрения (необязательно)

Содержание

Границы и контекст системы — как следует из названия — отделяют вашу систему (то есть вашу область) от всех её партнёров по взаимодействию (соседних систем и пользователей, то есть контекста вашей системы). Тем самым определяются внешние интерфейсы.

При необходимости разделите бизнес-контекст (входы и выходы, специфичные для предметной области) и технический контекст (каналы, протоколы, оборудование).

Мотивация

Интерфейсы предметной области и технические интерфейсы с партнёрами по взаимодействию относятся к самым критичным аспектам вашей системы. Убедитесь, что вы полностью их понимаете.

Форма

Различные диаграммы контекста
Списки партнёров по взаимодействию и их интерфейсов.

3.1 Бизнес-контекст

Содержание

Спецификация всех партнёров по взаимодействию (пользователей, ИТ-систем, …) с пояснениями входов и выходов или интерфейсов, специфичных для предметной области. При желании можно добавить форматы или протоколы взаимодействия, специфичные для предметной области.

Мотивация

Все заинтересованные стороны должны понимать, какие данные обмениваются с окружением системы.

Форма

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

В качестве альтернативы (или дополнения) можно использовать таблицу. Название таблицы — название вашей системы, три столбца содержат название партнёра по взаимодействию, входы и выходы.

3.2 Технический контекст

Содержание

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

Мотивация

Многие заинтересованные стороны принимают архитектурные решения на основе технических интерфейсов между системой и её контекстом. Особенно инфраструктурные или аппаратные проектировщики определяют эти технические интерфейсы.

Форма

Например, диаграмма развёртывания UML, описывающая каналы к соседним системам, вместе с таблицей отображения, показывающей отношения между каналами и входами/выходами.

4. Стратегия решения

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

Содержание

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

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

Мотивация

Эти решения — краеугольные камни вашей архитектуры. Они — основа для многих других детальных решений или правил реализации.

Форма

Объясняйте эти ключевые решения кратко.

Обоснуйте, что вы решили и почему вы решили именно так, исходя из вашей постановки проблемы, целей качества и ключевых ограничений. Ссылайтесь на подробности в последующих разделах (раздел 5 — для структурных деталей, раздел 8 — для сквозных концепций).

Можно использовать список подходов к решению или таблицу.

5. Представление строительных блоков

Статическая декомпозиция системы, абстракции исходного кода, показанные как иерархия белых ящиков (содержащих чёрные ящики) до соответствующего уровня детализации.

Содержание

Представление строительных блоков показывает статическую декомпозицию системы на строительные блоки (модули, компоненты, подсистемы, классы, интерфейсы, пакеты, библиотеки, фреймворки, слои, разделы, уровни, функции, макросы, операции, структуры данных, …), а также их зависимости (отношения, ассоциации, …)

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

Мотивация

Сохраняйте обзор своего исходного кода, делая его структуру понятной посредством абстракции.

Это позволяет общаться с заинтересованными сторонами на абстрактном уровне, не раскрывая деталей реализации.

Форма

Представление строительных блоков — это иерархический набор чёрных и белых ящиков (см. рисунок ниже) и их описаний.

5.1 Белый ящик: система в целом

Здесь вы описываете декомпозицию системы в целом с помощью следующего шаблона белого ящика. Он содержит

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

Поскольку существует так много способов определения интерфейсов, мы не предлагаем для них отдельного шаблона.

В лучшем случае вы обойдётесь примерами или простыми сигнатурами.

5.2 Уровень 2

Здесь можно определить внутреннюю структуру (некоторых) строительных блоков уровня 1 как белых ящиков.

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

5.2.1 Белый ящик для строительного блока 1

Определяет внутреннюю структуру строительного блока 1.

Используйте шаблон белого ящика (см. выше).

6. Представление времени выполнения

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

Содержание

Представление времени выполнения описывает конкретное поведение и взаимодействия строительных блоков системы в виде сценариев из следующих областей:

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

Замечание: главным критерием выбора возможных сценариев (последовательностей, рабочих процессов) является их архитектурная значимость. Описывать большое количество сценариев не важно. Лучше документировать репрезентативную выборку.

Мотивация

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

Форма

Существует много нотаций для описания сценариев, например

нумерованный список шагов (на естественном языке)
диаграммы активности или блок-схемы
диаграммы последовательности
BPMN или EPC (цепочки событийных процессов)
конечные автоматы
и т. д.

6.n Сценарий времени выполнения n (1, 2, 3 и т. д.)

Вставьте диаграмму времени выполнения или текстовое описание сценария.

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

7. Представление развёртывания

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

Содержание

Представление развёртывания описывает:

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

Часто системы выполняются в разных средах, например среде разработки, тестовой среде, производственной среде. В таких случаях следует документировать все уместные среды.

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

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

Мотивация

Программное обеспечение не работает без оборудования. Эта базовая инфраструктура может и будет влиять на вашу систему и/или некоторые сквозные концепции. Поэтому вам нужно знать инфраструктуру.

Форма

Возможно, диаграмма развёртывания самого высокого уровня уже содержится в разделе 3.2 как технический контекст с вашей собственной инфраструктурой как ОДНИМ чёрным ящиком. В этом разделе вы будете приближать этот чёрный ящик с помощью дополнительных диаграмм развёртывания.

UML предлагает диаграммы развёртывания для выражения этого представления. Используйте их, возможно, с вложенными диаграммами, когда ваша инфраструктура сложнее.
Если ваши (аппаратные) заинтересованные стороны предпочитают другие виды диаграмм вместо диаграммы развёртывания UML, позвольте им использовать любой вид, способный показать узлы и каналы инфраструктуры.

7.1 Инфраструктура, уровень 1

Опишите (обычно сочетанием диаграмм, таблиц и текста):

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

Для нескольких сред или альтернативных развёртываний скопируйте этот раздел arc42 для всех уместных сред. **

7.2 Инфраструктура, уровень 2

Здесь можно включить внутреннюю структуру (некоторых) элементов инфраструктуры из уровня 1 инфраструктуры.

Скопируйте структуру из уровня 1 для каждого выбранного элемента.

8. Сквозные концепции

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

Содержание

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

Мотивация

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

Это место в шаблоне, которое мы предусмотрели для связной спецификации таких концепций.

Многие из этих концепций связаны с несколькими вашими строительными блоками или влияют на них.

Форма

Форма может быть разной:

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

Структура этого раздела

Выберите только самые нужные темы для вашей системы и присвойте каждой заголовок уровня 2 в этом разделе (например, 8.1, 8.2 и т. д.).

НЕ ПЫТАЙТЕСЬ охватить все темы вышеупомянутой диаграммы.

Предыстория

Некоторые темы внутри систем часто касаются нескольких строительных блоков, элементов оборудования или процессов разработки. Сообщать или документировать такие сквозные темы может быть проще в одном центральном месте, а не повторять их в описании затронутых строительных блоков, элементов оборудования или процессов разработки.

Некоторые концепции могут касаться всех элементов системы, другие могут быть актуальны лишь для нескольких.

9. Архитектурные решения

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

Содержание

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

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

Мотивация

Заинтересованные стороны вашей системы должны иметь возможность понять и проследить ваши решения.

Форма

ADR (запись архитектурного решения) для каждого важного решения
список или таблица, упорядоченные по важности и последствиям, или
более подробно в виде отдельных разделов для каждого решения

Предыстория (об ADR)

Небольшие фрагменты документации легче читать, создавать и сопровождать. Когда речь идёт об архитектурных решениях, команды разработки часто:

знают о решении, поскольку оно видно, например, в исходном коде, но
не знают мотивации этого решения (см. Nygard 2011)

Поэтому вам следует документировать несколько важных решений вместе с их мотивацией и рассуждениями

Наше предложение относительно решений

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

10. Требования к качеству

Требования к качеству в виде сценариев, с деревом качества для общего обзора. Самые важные цели качества должны быть описаны в разделе 1.2 (цели качества).

Содержание

Этот раздел содержит все уместные требования к качеству.

Самые важные из этих требований уже описаны в разделе 1.2 (цели качества), поэтому здесь на них следует только ссылаться. В этом разделе 10 вам следует также зафиксировать менее важные требования к качеству, невыполнение которых полностью не создаст высоких рисков (но которые желательно иметь).

Мотивация

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

Дополнительная информация

См. обширную модель качества Q42 на https://quality.arc42.org.

10.1 Обзор требований к качеству

Содержание

Обзор или резюме требований к качеству.

Мотивация

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

Если эти обобщённые описания уже достаточно точны, конкретны и измеримы, раздел 10.2 можно пропустить.

Форма

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

В литературе также описана идея дерева атрибутов качества, в котором общий термин «качество» выступает корнем, а термин «качество» уточняется в виде дерева. [Bass+21] ввёл для этого термин «Quality Attribute Utility Tree».

10.2 Сценарии качества

Содержание

Сценарии качества конкретизируют требования к качеству и позволяют решить, выполнены ли они (в смысле критериев приёмки). Убедитесь, что ваши сценарии конкретны и измеримы.

Особенно полезны два вида сценариев:

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

Форма

Типичная информация для подробных сценариев включает следующее:

В краткой форме (предпочитаемой в модели Q42):

Контекст/предыстория: какой вид системы или компонента, какова среда или ситуация?
Источник/стимул: кто или что инициирует или запускает поведение, реакцию или действие.
Метрика/критерий приёмки: реакция, включающая меру или метрику

Длинная форма сценариев (предпочитаемая SEI и [Bass+21]) более подробна и включает следующую информацию:

Идентификатор сценария: уникальный идентификатор сценария.
Название сценария: короткое описательное название сценария.
Источник: сущность (пользователь, система или событие), инициирующая сценарий.
Стимул: запускающее событие или условие, на которое система должна отреагировать.
Среда: операционный контекст или условие, при котором система испытывает стимул.
Артефакт: строительные блоки или другие элементы системы, затронутые стимулом.
Реакция: результат или поведение, проявляемое системой в ответ на стимул.
Мера реакции: критерии или метрика, по которой оценивается реакция системы.

См. также

С января 2023 года arc42 предоставляет прагматичную модель качества, которая предлагает помечать требования к качеству хэштегами или метками вроде #flexible, #efficient, #usable, #operable, #testable, #secure, #safe, #reliable.

11. Риски и технический долг

Известные технические риски или технический долг. Какие потенциальные проблемы существуют внутри системы или вокруг неё? Что вызывает у команды разработки чувство неудовлетворённости?

Содержание

Список выявленных технических рисков или технического долга, упорядоченный по приоритету

Мотивация

«Управление рисками — это управление проектами для взрослых» (Тим Листер, Atlantic Systems Guild.)

Это должно быть вашим девизом при систематическом выявлении и оценке рисков и технического долга в архитектуре, что потребуется заинтересованным сторонам из руководства (например, менеджерам проектов, владельцам продуктов) как часть общего анализа рисков и планирования мер.

Форма

Список рисков и/или технического долга, возможно, с предлагаемыми мерами по минимизации, смягчению или предотвращению рисков или сокращению технического долга.