ADR 与 NFR：架构决策与系统质量并非同一回事

非功能需求（NFR）描述了系统预期满足的质量、约束或运行条件。架构决策记录（ADR）记录了为响应需求、约束、风险和权衡而做出的具有架构重要性的选择。它们相互关联，但不可互换：NFR 陈述必须为真的事项；ADR 解释决定了什么、为什么以及带来什么后果。

NFR 和 ADR 有什么区别？

最简单的区别在于语法。需求描述系统必须满足的条件。决策记录描述团队做出的选择。

例如，“在约定的参考负载下，API 必须在 300 毫秒内返回 95% 的读请求” 是一项质量需求。“对此工作负载使用读穿透缓存，因为仅使用数据库的实测路径无法在不产生不可接受成本的情况下满足延迟目标” 是一项架构决策。

即使实现发生变化，第一条陈述仍然有效。如果工作负载、技术、成本模型或证据发生变化，第二条陈述以后可能被另一项决策取代。

NFR 和 ADR 回答不同的问题

	NFR / 质量需求	ADR / 架构决策
主要问题	What quality, constraint, or operating condition must the system satisfy?	What architecturally significant choice did we make, and why?
典型内容	Measurable target, scope, condition, constraint, acceptance or validation rule	Context, decision, rationale, alternatives, trade-offs, status and consequences
生命周期角色	A requirement to design for and validate	A historical record of a significant decision
什么能证明它？	Measurement, test, analysis, inspection, audit or other validation evidence	The record proves what was decided, not that the resulting system meets the requirement
何时变化	When stakeholder need, operating conditions, policy or quality target changes	When the decision is replaced, rejected, deprecated, or superseded

从精确的架构角度来说，什么是 NFR？

“非功能需求”是一个方便的行业标签，但它可能掩盖几种不同类型的陈述。在架构工作中，有用的区分是功能行为、质量需求和约束。

ISO/IEC 25010:2023 提供了一个产品质量模型，包含九个特性和子特性，可用于规定和评估 ICT 及软件产品质量。SEI 架构工作同样将质量属性需求视为软件架构的主要驱动因素。

因此，有用的 NFR 不是“系统应该快”或“平台必须安全”。这些陈述只是命名了愿望。驱动架构的需求应使预期属性足够可测试，以便能够根据它评估设计替代方案和后续证据。

什么是架构决策记录？

架构决策记录是对重要架构决策的简洁记录。Michael Nygard 最初的 ADR 表述强调上下文、决策、其状态以及由此产生的后果。

重要的对象是决策，而不是模板。不同团队使用不同的 ADR 格式。更丰富的记录还可以保留替代方案、决策标准、权衡、证据、与需求的链接，以及决策适用的日期或版本。

ISO/IEC/IEEE 42010:2022 比 ADR 实践范围更广：它规定了架构描述及其概念的要求，同时明确不规定记录架构描述的单一过程、符号、工具、格式或媒介。因此，ADR 是一种实用的决策记录技术，而不是 ISO 42010 强制要求的格式。

最简单的例子：延迟需求 → 架构决策

假设产品负责人和工程团队一致认为，在定义的参考工作负载下，搜索端点必须在第 95 百分位内于 400 毫秒内返回第一页结果。

该目标不是 ADR。它是一个质量需求。架构工作始于询问在系统的其他约束下，什么设计可以满足它。

从需求到证据

1

1. 陈述需求

定义质量目标、工作负载、范围、阈值和验证方法。

2

2. 识别架构重要性

确定该需求是否实质性地影响结构、技术、部署、数据流或运营模式。

3

3. 评估选项

比较索引、缓存、反规范化、异步工作、分区或不同查询架构等备选方案。

4

4. 记录决策

在 ADR 中记录所选的架构选择、理由、备选方案、权衡、状态和后果。

5

5. 实施

将决策转化为代码、基础设施、配置和运营行为。

6

6. 验证

根据原始需求测量真实系统。测试结果验证 NFR；仅 ADR 本身不能验证。

NFR 和 ADR 通常具有多对多关系

一个质量需求可以驱动多个架构决策。例如，租户隔离需求可以影响身份传播、数据库作用域、后台作业设计、缓存键、审计日志和管理工具。

一个架构决策也可以同时响应多个需求。选择异步处理边界可能会提高响应能力和故障隔离，同时引入一致性、复杂性、可观测性和运营权衡。

为什么关系不是一对一的

	需求侧	决策侧	验证侧
一个 NFR → 多个 ADR	A broad quality target can constrain several architectural boundaries	Several coordinated decisions may be required	Evidence may need multiple tests or measurements
多个 NFR → 一个 ADR	Several quality and constraint drivers can point at the same design problem	One decision may balance several drivers	Each requirement still needs its own acceptance evidence
没有经典 NFR 的 ADR	The driver may be a functional need, policy, ecosystem constraint, cost or delivery condition	The choice can still be architecturally significant	Validate against the actual driver, not an invented NFR
需求稳定，ADR 变化	The target can remain unchanged	A better or necessary implementation choice can supersede the old decision	The new architecture must still be checked against the same target

技术选择并不自动成为需求

一个反复出现的架构错误是将首选技术写入需求层，然后将由此产生的设计视为不可避免。

如果合同、平台政策、兼容性要求、许可规则、组织标准或现有运营边界确实强制要求 PostgreSQL，那么“系统必须使用 PostgreSQL”可以是一个合法约束。但如果真正的需求是事务一致性、结构化查询、运营熟悉度或特定的恢复目标，需求应陈述该需求，技术选择应记录为决策。

ADR 不是 NFR 已满足的证明

决策文档和系统验证回答不同的问题。ADR 可以表明性能、安全性、弹性或可维护性已被考虑。它本身不能证明交付的系统实际实现了这些属性。

证明必须来自适合该需求的验证方法：基准测试、负载测试、故障测试、安全测试、架构分析、审计、检查、运营遥测、恢复演练、用户研究或其他形式的证据。

非功能需求何时变得具有架构意义？

并非每个非功能需求都值得做出架构决策。重要的子集是那些实质性地塑造架构或迫使整个系统进行权衡的需求。

SEI 文献使用架构重要需求这一概念来指代具有深远架构影响的需求。性能、可靠性、安全性和可修改性等质量属性是此类驱动因素的常见来源，尤其是当它们承载高业务或任务价值时。

架构重要性测试

1

1. 询问该需求是否改变结构

不同的取值是否会迫使产生不同的组件、边界、数据路径或部署拓扑？

2

2. 询问它是否约束重大技术选择

它是否会排除原本可行的实现选项？

3

3. 询问它是否产生横切行为

它是否影响许多组件、团队、接口或生命周期阶段？

4

4. 询问它是否产生困难的权衡

改善此属性是否会实质性地影响另一个质量、成本、进度、复杂性或风险？

5

5. 询问失败是否代价高昂

未满足该需求是否会造成重大的运营、安全、监管、财务或产品影响？

6

6. 仅在推理值得保留之处记录决策

不要为每个局部编码选择创建 ADR；保留具有架构意义的决策及其理由。

更强的架构模型：需求 → 决策 → 实现 → 验证

非功能需求与 ADR 之间最有用的联系是可追溯性。需求应能够指向处理它的架构决策；ADR 应识别它所响应的驱动因素；实现工作应落实该决策；验证应回到原始需求。

架构可追溯性链

1

需求 / 业务目标

该质量或约束为何重要。

2

需求 / 非功能需求

系统必须达成或遵守什么。

3

架构驱动因素

哪些需求重要到足以塑造设计。

4

选项

处理该驱动因素的可行方式。

5

ADR

所选选择、理由、替代方案、权衡和后果。

6

实现

实现该决策的代码、数据模型、基础设施、接口和运营机制。

7

验证证据

测试、测量、分析或审计，证明原始需求是否实际得到满足。

8

变更 / 取代

新证据或需求变化可以触发新的 ADR，同时保留历史推理。

实现证据：我如何在 SenseFlow 中区分需求与决策

在 SenseFlow 中，项目的事实来源明确将非功能需求置于需求结构内，与依赖关系、风险、假设、验收标准和验证方法放在一起。文档模型另行定义了重大决策的决策完整性。

对于 SenseFlow 的重大决策，记录的字段为决策、原因、替代方案、权衡、状态和日期 / 版本。重大架构和产品决策旨在保持历史可追溯，而不是在项目演进时被覆盖。

SenseFlow 还为 Confluence 和 Jira 分配了不同的运营角色。Confluence 是结构化的知识和决策环境；Jira 管理可执行的交付工作。重大 Jira Epic 应链接回相关的产品或需求文档。这保留了从产品意图到需求、决策再到实现的链条，而不是让待办事项列表成为架构的事实来源。

企业项目背景：需求应先于架构选择

同样的区分在面向企业的项目工作中也很有用。在需求、风险、约束和验收条件被充分理解之前做出的架构决策，可能会将偏好变成虚假的必需品。

对于 Enterprise Aaasaasa 0.1，相关教训是方法论层面的，而不是关于某个特定 ADR 的主张：需求、架构、验证、里程碑、风险管理和验收属于一个相互连接的交付系统。架构选择应保持可追溯到它旨在处理的需求或约束。

当ADR和NFR混在一起时的常见失败模式

ADR–NFR决策框架

当团队遇到新的架构关注点时，以下顺序有助于确定什么属于需求、什么属于ADR，以及什么属于证据。

ADR–NFR分类测试

1

1. 这是必需属性还是外部约束？

如果是，在选择机制之前先编写或引用该需求。

2

2. 它可以被验证吗？

定义所需的范围、条件、度量、验收规则、分析方法或其他证据。

3

3. 它具有架构重要性吗？

确定该需求是否实质性地影响结构、技术、数据、部署或横切权衡。

4

4. 是否存在有意义的替代方案？

比较可行的策略或架构选项，而不是直接跳到首选技术。

5

5. 某个选择是否已成为权威？

创建或更新ADR，包含上下文、决策、理由、替代方案、权衡、状态和后果。

6

6. 决策是否已实现？

将ADR追溯到设计、任务、代码、配置和运维。

7

7. 需求是否已满足？

针对需求本身收集验证证据。

8

8. 条件是否发生变化？

重新评估需求，并在必要时取代ADR而不抹除历史。

ADR和NFR不是什么

常见类别错误

	概念	它不是	原因
NFR / 质量需求	A required quality, constraint or operating condition	A technology shopping list	Requirements should preserve the need independently from one implementation when possible
ADR	A record of an architecturally significant decision	The complete architecture description	Architecture also needs views, interfaces, models, responsibilities and other documentation
验证证据	Evidence that checks whether a requirement is satisfied	The ADR itself	Documented intent is different from measured or analyzed system behavior
待办事项	Actionable delivery work	A durable substitute for architecture rationale	Task state answers what is being delivered, not necessarily why the architecture exists
约束	A condition that restricts the solution space	Always an internally chosen architecture decision	Some constraints come from regulation, contracts, existing platforms or organizational boundaries

什么会改变这个答案？

术语可能会演变。截至2026年10月8日，ISO/IEC/IEEE 29148:2018仍是当前发布的需求工程标准，但ISO列出了一项旨在取代它的国际标准草案。如果新版更改了相关术语或需求指南，本文中特定版本的引用应予以更新。

ADR模板也可以演变，而不会改变核心区别。Michael Nygard的最小模板、MADR、组织特定模板、架构知识工具或结构化决策数据库都可以记录决策。持久的问题是，该记录是否保留了足够的上下文和理由，以理解一项具有架构重要性的选择。

只有当组织有意选择一种组合工件，将需求和决策数据存储在同一文档中时，这种区别才会消失。即便如此，语义角色仍然不同：一个字段陈述所需的结果或约束；另一个字段记录所选的响应。

局限性

本文使用NFR作为实用简称。一些工程方法更倾向于使用质量属性需求、质量需求、系统质量、约束、服务水平目标或架构重要需求等术语。这些术语并非完全可以互换，项目术语应明确。

并非每个需求都能简化为单一数值阈值。安全性、安全、可维护性、互操作性、可用性、可解释性、可移植性和治理可能需要场景、结构规则、分析、过程控制和定性证据的组合。“可度量”应意味着对决策足够可验证，而不是人为地数字化。

并非每个架构决策都需要正式的ADR。文档成本应与架构重要性、寿命、不确定性、权衡复杂性和丢失理由的成本成比例。

结论

ADR和NFR属于架构工作的不同层次。NFR定义质量目标、约束或运行条件。ADR记录对一个或多个驱动因素的重要架构响应。

保持这些层次分离可以使架构更容易推理。需求可以独立于技术进行验证。决策可以被取代而无需重写历史。替代方案和权衡保持可见。交付工作可以追溯到架构意图。证据可以显示最终系统是否实际满足需求。

因此，最坚固的链条不是“NFR → ADR → 完成”。而是需求 → 要求 → 架构驱动因素 → 选项 → 决策 → 实现 → 验证 → 变更。这条链条将架构文档从静态文书转变为可测试的记录，说明系统为何具有其现有形态。

常见问题

ADR 与 NFR

ADR 是非功能性需求吗？

不是。NFR 陈述的是所需的品质、约束或运行条件。ADR 记录的是针对需求、约束、风险和权衡所做的具有架构重要性的选择。

每个 NFR 都应该有一个 ADR 吗？

不是。只有对架构产生实质性影响、值得保留架构级决策的需求才需要。一个 NFR 也可以驱动多个 ADR，一个 ADR 也可以响应多个需求。

“使用 PostgreSQL”可以是 NFR 吗？

只有当 PostgreSQL 确实作为外部约束被强制要求时才可以。否则，应首先表达底层需求，而选择 PostgreSQL 通常应被视为架构决策。

ADR 能证明性能或安全需求得到满足吗？

不能。ADR 记录的是意图和推理。需求通过适当的证据来验证，例如测试、测量、分析、审计或运行遥测。

ADR 应包含什么？

至少，ADR 应明确说明背景和决策。常见结构还包括状态和后果。团队可以添加备选方案、理由、权衡、需求链接、证据、负责人、日期和取代关系。

什么使 NFR 具有架构重要性？

当需求实质性影响系统结构、技术、数据流、部署、横切行为或困难的品质权衡时，尤其是当失败会带来高业务或任务影响时，该需求就具有架构重要性。

架构变更时，旧的 ADR 应删除吗？

通常不应删除。替代决策通常应取代旧记录，以便历史推理仍可追溯。

术语表

核心架构术语

NFR

非功能性需求：对所需系统品质、约束或运行条件的实用简称；确切术语因方法和标准而异。

质量属性需求

描述系统在既定条件下预期表现出的质量特性的需求，例如性能、可用性、安全性、可靠性或可修改性。

架构决策记录（ADR）

对具有架构重要性的决策及其足够背景的持久记录，以便理解为何做出该选择以及会产生什么后果。

架构重要需求（ASR）

具有足够深远架构影响、能实质性影响系统设计的需求。

约束

限制解决方案空间的条件，包括外部政策、法规、平台、兼容性、合同或组织边界。

权衡

一种设计关系，其中改善一个目标、属性或成本维度可能会使另一个变差。

验证

用于确定已实现系统在相关条件下是否满足所述需求的证据生成工作。

被取代的 ADR

已被更新的权威决策取代、但仍可用于追溯的历史决策记录。

主要来源与实施证据

本文将当前标准与项目实施证据区分开来。截至 2026 年 10 月 8 日，ISO/IEC/IEEE 29148:2018 仍然有效，但已标记为待修订；ISO/IEC 25010:2023 和 ISO/IEC/IEEE 42010:2022 是当前已发布的版本。SenseFlow 是上述可追溯性和决策完整性模型的原创项目证据。

ISO/IEC/IEEE 29148:2018 — 需求工程

当前已发布的需求工程标准。ISO 表示，2018 年版已于 2024 年审查并确认，预计将由目前正在制定的 DIS 取代。

ISO/IEC/IEEE DIS 29148 — 需求工程

目前正在制定、旨在取代 ISO/IEC/IEEE 29148:2018 的国际标准草案。

ISO/IEC 25010:2023 — 产品质量模型

当前产品质量模型，包含九个质量特性，用于规定、测量和评估 ICT 与软件产品质量。

ISO/IEC/IEEE 42010:2022 — 架构描述

当前架构描述标准。它规定了架构描述概念和一致性要求，但不规定单一记录格式、表示法、过程或工具。

Michael Nygard — 记录架构决策

具有影响力的原始 ADR 文章，描述了以背景、决策、状态和后果为中心的轻量级记录，并保留被取代的决策以便理解历史。

SEI — 将业务目标与架构重要需求关联起来

SEI 报告，解释质量属性需求和业务目标如何驱动软件架构，以及为何需要明确引出架构重要需求。

SEI — 定义非功能性系统质量

SEI 概述，将非功能性/质量属性与架构、场景、权衡和客观系统评估联系起来。

SEI — 属性驱动设计方法集合

基于功能需求、质量属性需求和约束的架构设计方法，选择架构战术和模式以满足质量场景。

SEI — 视图与超越集合

架构文档指南，强调相关视图以及将必要设计决策作为架构工作的一部分记录下来。