当前位置：首页 > news >正文

技术架构文档的写作规范：ADRs(Architecture Decision Records)从原理到实践

news 2026/7/16 18:30:42

技术架构文档的写作规范：ADRs(Architecture Decision Records)从原理到实践

一、架构知识流失——为什么"口口相传"的架构决策必然失败

技术团队的架构知识流失是一种慢性病。一个关键的架构决策——为什么选择了消息队列A而非B、为什么数据库表设计采用反范式化、为什么微服务拆分以这个边界为准——如果只存在于当事人的头脑中或某次会议的纪要里，随着人员流动和时间推移，这些决策的"为什么"将彻底消失。

后果是双重的：

新人困惑：新成员看到代码中的非直觉设计，无法判断这是"刻意的架构权衡"还是"历史的遗留债务"。前者需要维护，后者需要重构。
决策反复：当原有决策的条件发生变化（如流量增长10倍、数据量突破阈值），团队缺乏上下文来判断原决策的前提是否依然成立，导致在同样的问题上重复讨论。

ADRs（Architecture Decision Records）正是为解决这一问题而生的轻量级文档范式。它不追求架构文档的系统性和完整性，而是聚焦于记录单个决策的上下文、方案对比、选择理由和后果。一个ADRs文件短则一页，长则三四页，但信息密度极高——读者能在5分钟内理解一个关键决策的来龙去脉。

二、ADRs的核心结构——从Michael Nygard模板到团队自定义规范

ADRs 的经典模板由 Michael Nygard 在2011年提出，包含五个核心章节。一个良好的 ADR 文档具有极高的信息密度和自包含特性。

标题规范：采用ADR-NNNN: 决策的简要描述格式。编号使用自增序列，不重新编排。标题应当概括"做什么决策"，如"ADR-0003: 采用PostgreSQL的JSONB列存储非结构化元数据"，而非"关于数据库选型的讨论"。

状态机是ADR的生命周期管理核心。状态流转规则：

Draft → Proposed：初稿完成，提交团队评审
Proposed → Accepted：团队达成共识，ADR成为正式记录
Accepted → Superseded：新决策取代旧决策，ADR头部引用新ADR编号
Accepted → Deprecated：决策因架构演进自然过期（如微服务下线）

背景章节要回答"为什么现在做这个决策"和"如果不做决定会怎样"。不是描述技术方案的细节，而是描述面临的具体技术约束和业务需求。比如："当前的MySQL单表已增长到5000万行，按月分区策略导致跨月查询需要扫描所有分区，p99延迟已恶化到3秒。"

决策章节需要阐述"我们决定做什么"以及"为什么是这个方案"。关键不是罗列方案特性，而是说明权衡（trade-off）的逻辑——为什么接受A的成本换取B的收益。如果列出了备选方案，需要逐一说明为什么不选。

后果章节是ADR最有价值的部分。它分为两个方向：

正向：哪些问题被解决了，什么变得更容易
负向：引入了什么新成本，什么变得更困难，需要注意哪些风险

三、ADR管理工具——模板驱动的规范化生成与检索

以下代码实现了一套ADR生命周期管理工具，确保团队以统一格式生成和管理架构决策记录：

""" ADR（Architecture Decision Records）管理工具 支持模板生成、状态管理、关联检索和Markdown渲染 """ from dataclasses import dataclass, field from datetime import datetime from pathlib import Path from typing import Optional from enum import Enum class ADRStatus(str, Enum): """ADR状态枚举""" DRAFT = "draft" PROPOSED = "proposed" ACCEPTED = "accepted" SUPERSEDED = "superseded" DEPRECATED = "deprecated" @property def label(self) -> str: labels = { "draft": "草案", "proposed": "提议中", "accepted": "已接受", "superseded": "已取代", "deprecated": "已废弃", } return labels[self.value] @dataclass class ADR: """ADR数据模型""" id: int title: str status: ADRStatus context: str # 背景 decision: str # 决策 consequences: str # 后果 alternatives: list[str] = field(default_factory=list) superseded_by: Optional[int] = None supersedes: Optional[int] = None created_at: datetime = field(default_factory=datetime.now) updated_at: datetime = field(default_factory=datetime.now) tags: list[str] = field(default_factory=list) def filename(self) -> str: """生成标准文件名""" slug = ( self.title.lower() .replace(" ", "-") .replace("(", "") .replace(")", "") ) return f"ADR-{self.id:04d}-{slug}.md" class ADRGenerator: """ADR文档生成器：从数据模型生成Markdown格式文档""" TEMPLATE = """# {title} - **状态**: {status} - **日期**: {date} - **标签**: {tags} {superseded_section}{supersedes_section} ## 背景与上下文 {context} ## 决策 {decision} ## 备选方案 {alternatives} ## 后果与影响 {consequences} """ def generate(self, adr: ADR) -> str: tags_str = ", ".join(adr.tags) if adr.tags else "—" superseded = "" if adr.superseded_by: superseded = f"- **已被取代**: ADR-{adr.superseded_by:04d}\n" supersedes = "" if adr.supersedes: supersedes = f"- **取代**: ADR-{adr.supersedes:04d}\n" alternatives_text = "" if adr.alternatives: items = [ f"- **备选{i+1}**: {alt}" for i, alt in enumerate(adr.alternatives) ] alternatives_text = "\n".join(items) else: alternatives_text = "（未记录备选方案）" return self.TEMPLATE.format( title=adr.title, status=adr.status.label, date=adr.updated_at.strftime("%Y-%m-%d"), tags=tags_str, superseded_section=superseded, supersedes_section=supersedes, context=adr.context.strip(), decision=adr.decision.strip(), alternatives=alternatives_text, consequences=adr.consequences.strip(), ) class ADRRepository: """ ADR仓库管理器 负责ADR的CRUD操作、索引管理和关联查询 """ INDEX_HEADER = """# 架构决策记录索引 | 编号 | 标题 | 状态 | 日期 | |------|------|------|------| """ def __init__(self, root_dir: str = "docs/adr"): self.root = Path(root_dir) self.root.mkdir(parents=True, exist_ok=True) self.generator = ADRGenerator() self._adrs: dict[int, ADR] = {} self._load_existing() def create(self, adr: ADR) -> str: """创建新的ADR""" if adr.id in self._adrs: raise ValueError(f"ADR-{adr.id:04d} 已存在") # 分配编号 if adr.id == 0: adr.id = max(self._adrs.keys(), default=0) + 1 content = self.generator.generate(adr) filepath = self.root / adr.filename() filepath.write_text(content, encoding="utf-8") self._adrs[adr.id] = adr self._rebuild_index() return str(filepath) def supersede(self, old_id: int, new_adr: ADR) -> tuple[str, str]: """ 用新ADR取代旧ADR 自动更新旧ADR的状态和引用 """ if old_id not in self._adrs: raise ValueError(f"ADR-{old_id:04d} 不存在") old_adr = self._adrs[old_id] old_adr.status = ADRStatus.SUPERSEDED old_adr.superseded_by = new_adr.id new_adr.supersedes = old_id # 重新生成旧ADR self._save_adr(old_adr) # 创建新ADR new_path = self.create(new_adr) self._rebuild_index() return (str(self.root / old_adr.filename()), new_path) def get_active_adrs(self) -> list[ADR]: """获取所有活跃（已接受）的ADR""" return [a for a in self._adrs.values() if a.status == ADRStatus.ACCEPTED] def search_by_tag(self, tag: str) -> list[ADR]: """按标签检索ADR""" return [a for a in self._adrs.values() if tag in a.tags] def get_decision_chain(self, start_id: int) -> list[ADR]: """追踪决策链：从一个ADR出发，找出所有取代它的后续ADR""" chain = [] current_id = start_id visited = set() while current_id and current_id not in visited: visited.add(current_id) current = self._adrs.get(current_id) if not current: break chain.append(current) current_id = current.superseded_by return chain def _load_existing(self) -> None: """加载已有ADR文件""" for md_file in sorted(self.root.glob("ADR-*.md")): content = md_file.read_text(encoding="utf-8") adr = self._parse_adr(content, md_file.stem) if adr: self._adrs[adr.id] = adr def _parse_adr(self, content: str, filename: str) -> Optional[ADR]: """从Markdown内容解析ADR""" lines = content.split("\n") if not lines: return None title_line = lines[0].strip("# ") adr_id = 0 try: parts = filename.split("-") if len(parts) >= 2: adr_id = int(parts[1]) except ValueError: pass return ADR( id=adr_id, title=title_line, status=ADRStatus.ACCEPTED, context="", decision="", consequences="", ) def _save_adr(self, adr: ADR) -> str: """更新已有ADR文件""" adr.updated_at = datetime.now() content = self.generator.generate(adr) filepath = self.root / adr.filename() filepath.write_text(content, encoding="utf-8") self._adrs[adr.id] = adr return str(filepath) def _rebuild_index(self) -> None: """重建README索引""" rows = [] for adr in sorted(self._adrs.values(), key=lambda a: a.id): date_str = adr.updated_at.strftime("%Y-%m-%d") rows.append(f"| ADR-{adr.id:04d} | {adr.title} | {adr.status.label} | {date_str} |") index_content = self.INDEX_HEADER + "\n".join(rows) + "\n" (self.root / "README.md").write_text(index_content, encoding="utf-8") # ========== 使用示例 ========== if __name__ == "__main__": repo = ADRRepository(root_dir="./docs/adr") # 创建第一条ADR adr1 = ADR( id=0, # 自动分配 title="ADR-0001: 采用PostgreSQL的JSONB列存储非结构化元数据", status=ADRStatus.ACCEPTED, context=( "产品中的每个订单有10-50个动态扩展属性（如定制参数），" "传统EAV模式需要3张表联表查询，查询复杂度高。" "业务要求单次查询延迟 <200ms。" ), decision=( "使用PostgreSQL 14的JSONB数据类型存储动态扩展属性，" "配合GIN索引加速JSON路径查询，" "使用CHECK约束确保JSON Schema合规。" ), alternatives=[ "EAV（实体-属性-值）模式：灵活但查询复杂，不满足延迟要求", "MongoDB：需要引入新数据库组件，运维成本过高", "MySQL 8.0 JSON类型：支持不完善，性能弱于PG", ], consequences=( "正向：单表查询即可获取订单全量数据，延迟满足要求。\n" "负向：JSONB索引占用较多存储空间（约原始数据的30%），" "需要建立JSON Schema治理规范，" "开发团队需了解PG的JSON操作符。" ), tags=["database", "postgresql", "data-modeling"], ) path1 = repo.create(adr1) print(f"已创建: {path1}") # 获取所有活跃ADR active = repo.get_active_adrs() print(f"活跃ADR数量: {len(active)}") # 检索标签 db_adrs = repo.search_by_tag("database") print(f"数据库类ADR数量: {len(db_adrs)}")