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

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

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

1.1 Преглед на изискванията

Съдържание

Кратко описание на функционалните изисквания, движещите сили, извлечение (или резюме) на изискванията. Връзки към (надяваме се съществуващите) документи с изисквания, с информация къде да бъдат намерени.

Мотивация

От гледна точка на крайните потребители системата се създава или променя, за да подобри подкрепата на бизнес дейност и/или да подобри качеството.

Форма

Кратко текстово описание, вероятно във формат на таблица със случаи на употреба. Ако съществуват документи с изисквания, този преглед трябва да се позовава на тях.

Поддържайте тези откъси възможно най-кратки. Балансирайте четливостта на този документ с потенциалната излишност спрямо документите с изисквания.

1.2 Качествени цели

Съдържание

Трите (най-много пет) качествени цели за архитектурата, чието изпълнение е от най-голямо значение за основните заинтересовани страни. Наистина имаме предвид качествени цели за архитектурата. Не ги бъркайте с целите на проекта. Те не са непременно идентични. Стандартът ISO 25010 предоставя добър преглед на потенциални теми от интерес.

Мотивация

Трябва да знаете качествените цели на най-важните ви заинтересовани страни, тъй като те ще повлияят на фундаменталните архитектурни решения. Бъдете много конкретни относно тези качества, избягвайте модни думи. Ако вие като архитект не знаете как ще бъде оценявано качеството на вашата работа …

Форма

Таблица с най-важните качествени цели и конкретни сценарии, подредени по приоритет.

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

Съдържание

Изричен преглед на заинтересованите страни на системата, т.е. всички лица, роли или организации, които

трябва да знаят архитектурата
трябва да бъдат убедени в архитектурата
трябва да работят с архитектурата или с кода
се нуждаят от документацията на архитектурата за своята работа
трябва да вземат решения за системата или за нейната разработка

Мотивация

Трябва да знаете всички страни, участващи в разработката на системата или засегнати от системата. В противен случай може да получите неприятни изненади по-късно в процеса на разработка. Тези заинтересовани страни определят обхвата и нивото на детайлност на вашата работа и нейните резултати.

Форма

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

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

Всичко, което ограничава екипите при решенията за проектиране и реализация или решенията за свързани процеси. Понякога може да надхвърлят отделните системи и да важат за цели организации и компании.

Съдържание

Всяко изискване, което ограничава софтуерните архитекти в свободата им при решенията за проектиране и реализация или решенията за процеса на разработка. Тези ограничения понякога надхвърлят отделните системи и важат за цели организации и компании.

Мотивация

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

Форма

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

3. Контекст и обхват

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

Съдържание

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

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

Мотивация

Интерфейсите на предметната област и техническите интерфейси към партньорите в комуникацията са сред най-критичните аспекти на вашата система. Уверете се, че ги разбирате напълно.

Форма

Различни контекстни диаграми
Списъци с партньори в комуникацията и техните интерфейси.

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

Съдържание

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

Мотивация

Всички заинтересовани страни трябва да разбират какви данни се обменят със средата на системата.

Форма

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

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

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

Съдържание

Технически интерфейси (канали и преносни среди), свързващи вашата система с нейната среда. Освен това съпоставяне на специфичните за предметната област вход/изход с каналите, т.е. обяснение кой канал използва кой вход/изход.

Мотивация

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

Форма

Напр. UML диаграма на разполагането (deployment diagram), описваща каналите към съседните системи, заедно с таблица за съпоставяне, показваща връзките между каналите и входа/изхода.

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)

Затова трябва да документирате няколко важни решения заедно с тяхната мотивация, разсъждения

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

Поддържайте колекция от архитектурно значими решения, онези решения, които засягат структурата, качествените характеристики, важните (особено външните) зависимости и интерфейси или техниките на изграждане (благодарение на Michael Nygard за това предложение).

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]) е по-подробна и включва следната информация:

ID на сценария: Уникален идентификатор на сценария.
Име на сценария: Кратко, описателно име на сценария.
Източник: Субектът (потребител, система или събитие), който инициира сценария.
Стимул: Задействащото събитие или условие, което системата трябва да обработи.
Среда: Оперативният контекст или условие, при което системата преживява стимула.
Артефакт: Строителните блокове или други елементи на системата, засегнати от стимула.
Отговор: Резултатът или поведението, което системата проявява в отговор на стимула.
Мярка за отговора: Критерият или метриката, по които се оценява отговорът на системата.

Вижте също

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

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

Известни технически рискове или технически дълг. Какви потенциални проблеми съществуват в или около системата? Какво кара екипа за разработка да се чувства зле?

Съдържание

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

Мотивация

„Управлението на риска е управление на проекти за възрастни“ (Tim Lister, Atlantic Systems Guild.)

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

Форма

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