以下 ADR 议题与演进均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。“决策要记录、取代要指回旧记录、当前决策要能查到"这三条不变,具体议题按真实架构演进记录。
13.2 搭好了防线,这一节讲治理的最后一环:架构决策怎么被记住。ADR(架构决策记录)把"为什么这么定"写下来,让后来者不用考古。没有记录,架构就只剩当下的代码——没人知道为什么,也就没人敢改。
ADR 记录什么
一条 ADR 记四件事:
| 字段 | 内容 |
|---|---|
| 背景 | 当时面对什么问题 |
| 决策 | 最终怎么定的 |
| 后果 | 带来什么代价与收益 |
| 状态 | 有效 / 被取代 / 废弃 |
决策是最少的部分,背景与后果才是价值。 决策一句话说完,但为什么这么定、定了要付什么代价,才是后来者需要的。一个只有"用了 Redis"的 ADR 是没用的,要有"多实例后进程内缓存不一致,所以改用共享 Redis”。
supersedes:决策链
架构会演进,决策会被取代。新决策通过 supersedes 指回旧记录,形成一条决策链——从当前有效的决策一路回溯到最初。链回答"怎么一步步走到这里的"。
| ADR | 议题 | 状态 | supersedes |
|---|---|---|---|
| adr-001 | 缓存 | 被取代 | — |
| adr-002 | 缓存 | 有效 | adr-001 |
| adr-003 | 工具权限 | 被取代 | — |
| adr-004 | 工具权限 | 有效 | adr-003 |
最小实验:ADR 登记、查询与回溯
实验提供 ADR 与 ADRLog:add 登记,current_for 查当前有效决策,chain 回溯完整决策链。
# file: agp_lab/adr.py | write
# tier: 3
# verify: python3 -m unittest tests.test_adr
"""架构决策记录:把"为什么这么定"写下来,让后来者不用考古。
ADR 记录一条决策的背景、结论与后果;同一议题被新决策取代时
新记录通过 supersedes 指回旧记录,形成一条可追溯的决策链。
本模块演示如何登记、查询当前有效决策并回溯整条链。
"""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any
ACTIVE_STATUSES = ("accepted", "proposed")
@dataclass
class ADR:
id: str
topic: str
title: str
status: str
context: str
decision: str
supersedes: str | None = None
class ADRLog:
def __init__(self) -> None:
self.adrs: list[ADR] = []
def add(self, adr: ADR) -> None:
self.adrs.append(adr)
def _find(self, adr_id: str) -> ADR | None:
for adr in self.adrs:
if adr.id == adr_id:
return adr
return None
def current_for(self, topic: str) -> ADR | None:
for adr in reversed(self.adrs):
if adr.topic == topic and adr.status in ACTIVE_STATUSES:
return adr
return None
def chain(self, topic: str) -> list[str]:
current = self.current_for(topic)
if current is None:
return []
ids = [current.id]
while current.supersedes:
current = self._find(current.supersedes)
if current is None:
break
ids.append(current.id)
return ids
def demo() -> dict[str, Any]:
log = ADRLog()
log.add(ADR(
"adr-001", "cache", "进程内缓存承载状态",
"superseded", "单机场景要快", "用进程内 LRU 缓存", None,
))
log.add(ADR(
"adr-002", "cache", "共享缓存支撑多实例",
"accepted", "扩容到多实例后状态不一致", "改用共享 Redis", "adr-001",
))
log.add(ADR(
"adr-003", "tool_permission", "工具白名单",
"superseded", "内部工具少", "只放行已知工具", None,
))
log.add(ADR(
"adr-004", "tool_permission", "工具黑名单 + 灰度",
"accepted", "工具增长到上百个", "默认拒绝、黑名单放行", "adr-003",
))
return {
"current_cache": log.current_for("cache").id,
"current_tool_permission": log.current_for("tool_permission").id,
"chain_cache": log.chain("cache"),
"chain_tool_permission": log.chain("tool_permission"),
"chain_unknown": log.chain("billing"),
}
if __name__ == "__main__":
for key, value in demo().items():
print(f"{key}: {value}")
运行:
cd private/labs/agp-lab
python3 -m agp_lab.adr
输出:
current_cache: adr-002
current_tool_permission: adr-004
chain_cache: ['adr-002', 'adr-001']
chain_tool_permission: ['adr-004', 'adr-003']
chain_unknown: []
五条输出对应五件事:
- current_cache:缓存的当前决策是 adr-002。查当前决策不靠翻历史,
current_for直接给出有效的那条。 - current_tool_permission:工具权限当前是 adr-004。每个议题都有当前有效决策,议题与决策一一对应。
- chain_cache:回溯链
['adr-002', 'adr-001']——从共享缓存回溯到进程内缓存。演进路径一次看清:单机先进程内、多实例再共享。 - chain_tool_permission:
['adr-004', 'adr-003']——从黑名单回溯到白名单。两条演进线各有各的链。 - chain_unknown:未知议题返回空。查不到就是查不到,不伪造记录。
一个值得点破的细节:chain_cache 是 ['adr-002', 'adr-001']——链的头部是当前决策,尾部是最初决策。回溯的方向是"从现在到过去":新决策在链头,旧决策在链尾,演进顺序一目了然。而 chain_unknown 返回空列表——ADR 日志的诚实性在于"没有记录就说不没有",而不是模糊带过。这与 8.3 审计的"碰没碰过比拿没拿到更重要"是同一原则:记录要如实。
决策链的价值
决策链的回报在变更时兑现。要改架构,先读链——知道现状怎么来的,知道当初为什么这么定,才知道这次改要尊重什么、推翻什么。链是变更前的考古工具:没有链,改架构要么靠猜要么推倒重来。
| 变更场景 | 决策链提供的 |
|---|---|
| 改缓存方案 | 为什么从进程内到共享 |
| 调工具权限 | 为什么从白名单到黑名单 |
| 复盘历史问题 | 当时权衡了什么 |
治理的落地
ADR 是治理的地基,但它要配套机制才有效。决策要有负责人(10.1 的责任链同样适用——每条 ADR 有决策者);决策要可审计(8.3 的审计记录谁在何时查了哪条 ADR);决策链要可追踪(12.1 的追踪把"这次变更基于哪条 ADR"记下来)。ADR 不是文档,是治理结构的证据——责任、审计、追踪三套机制都消费它。
与参考架构的关系
ADR 与参考架构相辅相成。参考架构是当前的静态快照——现在的系统长什么样;ADR 是演进的时间线——怎么一步步长成这样的。两者互为补充:参考架构告诉后来者"现在是这样",ADR 告诉后来者"为什么是这样"。一个完整的治理,既要快照也要时间线。
ADR 的模板
ADR 要有固定模板,记录才整齐。背景、决策、后果、状态之外,加决策人与日期——决策人是 10.1 责任链在治理层的对应,日期让决策链有时间坐标。模板统一,跨团队可读。
| 字段 | 必填 |
|---|---|
| 议题 | 是 |
| 背景 | 是 |
| 决策 | 是 |
| 后果 | 是 |
| 状态 | 是 |
| 决策人 | 是 |
模板的统一是治理效率的基础。 每张 ADR 字段一致,查询(current_for)与回溯(chain)才有稳定输入。没有模板,ADR 各写各的,治理工具就无从下手。
ADR 与代码的对应
ADR 要指回代码。每条 ADR 的决策,代码里要能找到对应物——改缓存方案,缓存实现里注释指向 adr-002;改工具权限,权限模块引用 adr-004。ADR 与代码双向可查:从 ADR 找到实现,从实现找到 ADR。
| 方向 | 手段 |
|---|---|
| ADR → 代码 | 注释 / 文档链接 |
| 代码 → ADR | 变更记录关联 |
双向对应让架构有据可查。 读代码遇到"为什么这样写",注释指向 ADR;评审 ADR 落地情况,从 ADR 找代码核对。没有对应,ADR 是孤岛,代码是孤岛,两者接不上治理就空转。
ADR 的评审节奏
ADR 要评审,不是写完就完。新 ADR 过评审(谁同意、后果认不认);旧 ADR 定期复核(决策是否还成立、要不要 supersedes)。评审节奏让决策链保持新鲜——过期的 ADR 挂着"有效"状态,等于治理里埋着过时的权威。
| 时机 | 动作 |
|---|---|
| 新决策 | 评审 + 登记 |
| 定期 | 复核有效性 |
| 架构变更 | 触发新 ADR |
评审与 13.1 威胁建模共享节奏。 架构变更触发 ADR,同时触发威胁模型重评——两个治理动作绑在一起,变更一次、评审一轮,别各走各的。
架构判据
ADR 是否合格,用五条判据检查:
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 决策有记录 | 每条决策有 ADR | 决策只有代码 |
| 背景后果俱全 | 记下为什么与代价 | 只有结论 |
| 当前可查 | current_for 有答案 | 现状靠考古 |
| 取代指回旧记录 | supersedes 成链 | 新决策覆盖旧的 |
| 链可回溯 | 演进路径可查 | 历史断链 |
判据第一条是"决策必须记录",判据第三条才是关键:当前决策要能直接查到,而不是翻历史。判据第五条是治理的完整闭环——决策链断在中间,演进就讲不清。
小结
- ADR 记四件事:背景、决策、后果、状态。
- 背景与后果才是价值,决策只是一句话。
- supersedes 把新决策指回旧记录,形成决策链。
- 决策链是变更前的考古工具。
- ADR 与责任、审计、追踪配套,才是完整的治理。
阅读导航:上一节:13.2 纵深防御:分层防护 · 下一节:目录与学习路径 。
常见错误与边界
- 决策只有代码。 没有 ADR,后来者只能考古,不敢改。
- 只有结论没背景。 “用了 Redis"没有"为什么”,等于没记。
- 现状靠翻历史。 没有 current_for,查当前决策要靠人肉。
- 新决策覆盖旧的。 不 supersedes,演进路径断链。
- ADR 悬空。 记了不配套责任/审计/追踪,治理空转。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。