Architecture Decision Recordarc42 的决策记录模板
1. 引言与目标
简要描述需求、驱动力量,以及需求的摘录(或摘要)。对主要利益相关者而言优先级最高的、前三项(最多五项)架构质量目标。一张列出重要利益相关者及其对架构的期望的表格。
1.1 需求概览
内容
简要描述功能需求、驱动力量,以及需求的摘录(或摘要)。提供指向(但愿已存在的)需求文档的链接,并说明可以在哪里找到它们。
动机
从最终用户的角度来看,创建或修改系统是为了更好地支持某项业务活动和/或提高质量。
形式
简短的文字描述,可能采用表格形式的用例格式。如果存在需求文档,此概览应引用这些文档。
请尽可能保持这些摘录简短。在本文档的可读性与相对于需求文档可能产生的冗余之间取得平衡。
1.2 质量目标
内容
对主要利益相关者而言,实现起来最重要的前三项(最多五项)架构质量目标。我们真正指的是架构的质量目标。不要将它们与项目目标混淆,两者未必相同。ISO 25010 标准很好地概述了可能值得关注的主题。
动机
你应该了解最重要的利益相关者的质量目标,因为它们会影响基本的架构决策。请务必把这些质量说得非常具体,避免使用流行术语。如果你作为架构师不知道自己的工作质量将如何被评判……
形式
一张按优先级排序的表格,列出最重要的质量目标和具体场景。
1.3 利益相关者
内容
对系统利益相关者的明确概览,即所有符合以下情形的人员、角色或组织:
应当了解该架构
必须被说服接受该架构
必须使用该架构或代码开展工作
工作中需要该架构的文档
必须就系统或其开发做出决策
动机
你应该了解参与系统开发或受系统影响的所有各方。否则,你可能会在开发过程的后期遇到令人不快的意外。这些利益相关者决定了你的工作及其成果的范围和详细程度。
形式
一张表格,包含角色名称、人员姓名,以及他们对架构及其文档的期望。
2. 约束
任何约束团队在设计与实现决策或相关流程决策方面的因素。有时可能超出单个系统的范围,对整个组织和公司有效。
内容
任何约束软件架构师在设计和实现决策或开发流程决策方面自由度的需求。这些约束有时超出单个系统的范围,对整个组织和公司有效。
动机
架构师应当确切地知道,在设计决策中哪些地方是自由的,哪些地方必须遵守约束。约束必须始终加以处理,不过它们有时是可以协商的。
形式
带有说明的简单约束表格。如有需要,可以将其细分为技术约束、组织与政治约束,以及约定(例如编程或版本管理指南、文档或命名约定)。
3. 背景与范围
划定你的系统与其(外部)通信伙伴(相邻系统和用户)之间的边界。规定外部接口。从业务/领域的视角(必须)或技术的视角(可选)呈现。
内容
系统范围与背景——顾名思义——将你的系统(即你的范围)与它所有的通信伙伴(相邻系统和用户,即系统的背景)划分开来,从而规定外部接口。
如有必要,请区分业务背景(特定领域的输入和输出)与技术背景(通道、协议、硬件)。
动机
与通信伙伴之间的领域接口和技术接口,是系统最关键的方面之一。请确保你完全理解它们。
形式
各种背景图
通信伙伴及其接口的列表。
3.1 业务背景
内容
规定所有通信伙伴(用户、IT 系统……),并说明特定领域的输入和输出或接口。你还可以选择性地添加特定领域的格式或通信协议。
动机
所有利益相关者都应当了解与系统环境交换了哪些数据。
形式
各类将系统视为黑盒、并规定与通信伙伴之间领域接口的图。
或者(或另外)你可以使用表格。表格的标题是你的系统名称,三列分别包含通信伙伴的名称、输入和输出。
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. 横切概念
在系统多个部分(→ 横切)中相关的总体性、原则性的规定和解决方案方法。概念通常与多个构建块相关。包含领域模型、架构模式和风格、使用特定技术的规则和实现规则等不同主题。
内容
本节描述横切概念(实践、模式、规定或解决方案思路)。这些概念通常与多个构建块相关。它们可能涵盖许多不同的主题。
动机
概念构成了架构概念完整性(一致性、同质性)的基础。因此,它们对于实现系统的内在质量是一项重要贡献。
这是我们在模板中为这类概念的统一规范所提供的位置。
这些概念中有许多与你的多个构建块相关或对其产生影响。
形式
形式可以多种多样:
结构任意的概念文档
示例实现,尤其适用于技术概念
使用架构视图表示法的横切模型摘录或场景
本节的结构
只选择你的系统最需要的主题,并在本节中为每个主题分配一个二级标题(例如 8.1、8.2 等)。
- 不要试图涵盖上述图中的所有主题。
背景
系统中的某些主题通常涉及多个构建块、硬件元素或开发流程。在一个集中的位置沟通或记录这类横切主题,可能比在相关构建块、硬件元素或开发流程的描述中重复它们更容易。
某些概念可能涉及系统的所有元素,另一些则可能只与少数元素相关。
9. 架构决策
重要的、代价高昂的、关键的、大规模的或有风险的架构决策,包括其理由。
内容
重要的、代价高昂的、大规模的或有风险的架构决策,包括其理由。这里的“决策”指的是根据给定标准选择一个备选方案。
请自行判断,一项架构决策应该记录在这个集中的章节中,还是更适合在局部记录(例如在某个构建块的白盒模板中)。避免重复的文字。请参阅第 4 章,你已经在那里记录了架构中最重要的决策。
动机
系统的利益相关者应当能够理解并回溯你的决策。
形式
为每项重要决策编写 ADR(架构决策记录)
按重要性和后果排序的列表或表格,或者
以每项决策单独成节的形式提供更详细的记录
背景(关于 ADR)
较小的文档片段更容易阅读、创建和维护。谈到架构决策时,开发团队往往:
知道这项决策,因为它在例如源代码中是可见的,但是
不清楚这项决策背后的动机(参见 Nygard 2011)
因此,你应该记录少数重要决策及其动机和推理
我们关于决策的建议
保留一份具有架构意义的决策集合,即那些影响结构、质量特性、重要(尤其是外部)依赖和接口,或构建技术的决策(感谢 Michael Nygard 的这一建议)。
10. 质量需求
以场景形式表达的质量需求,配以质量树以提供高层概览。最重要的质量目标应已在第 1.2 节(质量目标)中描述。
内容
本节包含所有相关的质量需求。
其中最重要的需求已经在第 1.2 节(质量目标)中描述过,因此在此处只需引用。在本第 10 章中,你还应当记录重要性较低的质量需求,这些需求即使没有完全实现也不会带来高风险(但最好能有)。
动机
由于质量需求会对架构决策产生很大影响,你应该以具体且可衡量的方式了解哪些质量对你的利益相关者真正重要。
更多信息
请参阅 https://quality.arc42.org 上内容全面的 Q42 质量模型。
10.1 质量需求概览
内容
质量需求的概览或摘要。
动机
我们经常遇到数十个(甚至数百个)详细的质量需求。在这一概览部分,你应该尝试进行总结,例如通过描述类别或主题(如 ISO 25010:2023 或 Q42 所建议的)。
如果这些摘要描述已经足够精确、具体且可衡量,你可以跳过第 10.2 节。
形式
使用一张简单的表格,每行包含一个类别或主题以及对质量需求的简短描述。或者,你也可以使用思维导图来组织这些质量需求。
文献中还描述过质量属性树的概念,它将通用术语“质量”作为根,并对“质量”一词进行树状细化。[Bass+21] 为此引入了“质量属性效用树”(Quality Attribute Utility Tree)这一术语。
10.2 质量场景
内容
质量场景使质量需求具体化,并使人们能够判断它们是否得到满足(就验收标准而言)。请确保你的场景具体且可衡量。
有两类场景尤其有用:
使用场景(也称为应用场景或用例场景)描述系统在运行时对某种刺激的反应。这也包括描述系统效率或性能的场景。示例:系统在一秒内对用户的请求做出反应。
变更场景描述对系统或其直接环境进行修改或扩展所期望的效果。示例:实现了额外的功能,或者对某个质量属性的需求发生了变化,并测量变更所需的工作量或持续时间。
形式
详细场景的典型信息包括以下内容:
简短形式(Q42 模型所倾向的形式):
背景/上下文:什么类型的系统或组件,环境或情况如何?
来源/刺激:谁或什么发起或触发某种行为、反应或动作。
度量/验收标准:包含度量或指标的响应
场景的长形式(SEI 和 [Bass+21] 所倾向的形式)更为详细,包含以下信息:
场景 ID:场景的唯一标识符。
场景名称:场景的简短描述性名称。
来源:发起该场景的实体(用户、系统或事件)。
刺激:系统必须应对的触发事件或条件。
环境:系统遇到该刺激时的运行背景或条件。
制品:受该刺激影响的构建块或系统的其他元素。
响应:系统针对该刺激所表现出的结果或行为。
响应度量:用于评估系统响应的标准或指标。
另请参阅
自 2023 年 1 月起,arc42 提供了一个务实的质量模型,建议使用 #flexible、#efficient、#usable、#operable、#testable、#secure、#safe、#reliable 等标签或标记来标注质量需求。
11. 风险与技术债务
已知的技术风险或技术债务。系统内部或周围存在哪些潜在问题?开发团队对哪些方面感到苦恼?
内容
按优先级排序的已识别技术风险或技术债务列表。
动机
“风险管理是成年人的项目管理”(Tim Lister,Atlantic Systems Guild)。
这应当成为你系统性地发现和评估架构中风险与技术债务的座右铭,管理层利益相关者(例如项目经理、产品负责人)在整体风险分析和度量规划中将需要这些信息。
形式
风险和/或技术债务的列表,可能还包括用于最小化、缓解或规避风险或减少技术债务的建议措施。