arc42 个决策记录模板

https://arc42.org/overview

1. 简介搭目标

简单描述需求、驱动力量，还有需求个摘录（或者摘要）。架构个前三个（最多五个）质量目标，对主要利益相关者优先级最高。再加一张表，列出重要个利益相关者，搭伊拉对架构个期望。

1.1 需求概览

内容

简单描述功能需求、驱动力量，还有需求个摘录（或者摘要）。链接到（希望已经存在个）需求文档，并且讲明辣啥地方找得着。

动机

从最终用户个角度看，创建或者修改一个系统，是为了更好地支持某项业务活动，和／或者提高质量。

形式

简短个文字描述，可能用表格形式个用例格式。要是已经有需求文档，迭个概览应该引用迭眼文档。

迭眼摘录要尽量简短。辣迭份文档个可读性，搭需求文档可能产生个重复之间求平衡。

1.2 质量目标

内容

架构个前三个（最多五个）质量目标，实现伊拉对主要利益相关者最为重要。阿拉真个是指架构个质量目标。勿要搭项目目标搞混，伊拉未必一样。ISO 25010 标准对可能感兴趣个话题做了一个蛮好个概览。

动机

侬应该晓得最重要个利益相关者个质量目标，因为伊拉会影响根本性个架构决策。对迭眼质量要讲得非常具体，勿要用流行词。要是侬做架构师个，勿晓得侬个工作质量会被哪能评判……

形式

一张表，列出最重要个质量目标搭具体场景，按优先级排序。

1.3 利益相关者

内容

明确概览系统个利益相关者，也就是所有符合下底情况个人、角色或者组织：

应该晓得架构
必须被说服接受架构
必须搭架构或者代码打交道
工作中需要架构文档
必须就系统或者系统开发做决定

动机

侬应该晓得参与系统开发，或者受系统影响个所有各方。否则，开发过程当中以后可能碰着讨厌个意外。迭眼利益相关者决定侬工作搭工作成果个范围搭详细程度。

形式

一张表，里向有角色名称、人名，还有伊拉对架构搭架构文档个期望。

2. 限制

任何限制团队辣设计搭实施决策，或者相关流程决策上个自由个东西。有辰光会超出单个系统，对整个组织搭公司有效。

内容

任何限制软件架构师辣设计搭实施决策，或者开发流程决策上个自由个需求。迭眼限制有辰光会超出单个系统，对整个组织搭公司有效。

动机

架构师应该精确晓得辣设计决策上啥地方是自由个，啥地方必须遵守限制。限制必须始终处理；勿过伊拉可能是可以协商个。

形式

带讲明个简单限制表。必要个话，可以细分成技术限制、组织搭政治限制，还有约定（比方编程或者版本指南、文档或者命名约定）

3. 背景搭范围

拿侬个系统搭伊个（外部）沟通对象（相邻系统搭用户）划清界限。规定外部接口。从业务／领域角度展示（始终）或者从技术角度展示（可选）

内容

系统范围搭背景——顾名思义——拿侬个系统（也就是侬个范围）搭伊所有沟通对象（相邻系统搭用户，也就是侬系统个背景）划清界限。这样就规定了外部接口。

必要个话，拿业务背景（特定领域个输入搭输出）搭技术背景（渠道、协议、硬件）区分开来。

动机

搭沟通对象之间个领域接口搭技术接口，是侬系统最关键个方面之一。确保侬完全理解伊拉。

形式

各种背景图
沟通对象搭伊拉接口个清单。

3.1 业务背景

内容

规定所有沟通对象（用户、IT 系统……），并且讲明特定领域个输入搭输出或者接口。可选地，可以加上特定领域个格式或者沟通协议。

动机

所有利益相关者应该了解，搭系统个环境之间交换啥个数据。

形式

各种拿系统当作黑盒展示、并且规定搭沟通对象之间个领域接口个图。

也可以（或者另外）用表格。表格个标题是侬系统个名字，三列分别是沟通对象个名字、输入搭输出。

3.2 技术背景

内容

拿侬个系统搭环境连起来个技术接口（渠道搭传输介质）。另外，还有特定领域输入／输出到渠道个对应，也就是讲明哪种 I/O 用哪个渠道。

动机

许多利益相关者根据系统搭伊背景之间个技术接口做架构决策。尤其是基础设施或者硬件设计师决定迭眼技术接口。

形式

比方 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）

所以侬应该记录几个重要个决策，连同伊拉个动机、推理

阿拉对决策个建议

保存一批架构上重要个决策，也就是影响结构、质量特性、重要（尤其是外部）依赖搭接口，或者构建技术个那眼决策（感谢 Michael Nygard 个迭个建议）。

10. 质量需求

质量需求用场景来表示，配质量树提供高层概览。最重要个质量目标应该已经辣 1.2 节（质量目标）里描述过。

内容

迭一节包含所有相关个质量需求。

其中最重要个需求已经辣 1.2 节（质量目标）里描述过，所以辣迭里只应该引用。辣迭个第 10 章里，侬还应该记录重要性较低个质量需求，伊拉要是勿完全达成，勿会造成高风险（但是有最好）。

动机

因为质量需求对架构决策会有许多影响，侬应该用具体、可度量个方式，晓得对侬个利益相关者来讲啥质量是真正重要个。

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。）

迭应该是侬系统地发现搭评估架构里风险搭技术债个座右铭，管理层个利益相关者（比方项目经理、产品负责人）作为整体风险分析搭度量计划个一部分，需要迭眼。

形式

风险和／或者技术债个清单，可能包括减少、缓解或者避免风险，或者减少技术债个建议措施。