ADR 架构决策记录: 让架构决策可追溯

# ADR 架构决策记录: 让架构决策可追溯 ## 什么是 ADR Architecture Decision Records (ADR) 是一种轻量级文档实践，用简短的结构化文本记录每个重要的架构决策。当新成员问"为什么用 PostgreSQL 而不是 MySQL"时，ADR 提供完整的上下文和理由。 ## 痛点场景 - 新人入职："为什么选了这个技术栈？" - 回头看代码："这个设计当时为什么这么做？" - 架构演进："之前的方案为什么被放弃了？" 没有 ADR 时，这些知识存在于某个人的脑子里，或者散落在过期的 Wiki 页面中。 ## ADR 模板 ```markdown # ADR-001: 使用 PostgreSQL 作为主数据库 ## 状态 已接受 (2024-01-15) ## 上下文 我们需要为新项目选择关系型数据库。团队当前主要使用 MySQL 8.0， 但新项目有以下特殊需求： - JSON 数据的复杂查询和索引 - 全文搜索（中英文） - 地理空间查询（门店定位功能） - 需要物化视图支持复杂报表 ## 考虑的方案 ### 方案 1: MySQL 8.0 (维持现状) - 优点：团队熟悉，运维经验丰富 - 缺点：JSON 索引能力有限，无原生全文搜索（中文），无物化视图 ### 方案 2: PostgreSQL 16 - 优点：原生 JSONB 索引，强大的全文搜索，PostGIS 地理空间，物化视图 - 缺点：团队需要学习，运维流程需要调整 ### 方案 3: MySQL + Elasticsearch - 优点：MySQL 保持熟悉度，ES 补全文搜索 - 缺点：双系统维护成本高，数据同步复杂度增加 ## 决策 选择 PostgreSQL 16。 ## 理由 1. 一个数据库满足所有需求，避免引入 ES 增加系统复杂度 2. PostgreSQL 的 JSONB 和 GIN 索引完美匹配我们的 JSON 查询需求 3. PostGIS 是地理空间查询的行业标准 4. 团队学习成本可控 — SQL 差异不大，两周内可上手 5. 云厂商对 PostgreSQL 的托管服务已经很成熟 ## 影响 - 运维团队需要学习 PostgreSQL 备份、监控、调优 - 需要建立 PostgreSQL 的 CI/CD 迁移流程 - ORM 从 MyBatis 切换到 JPA（PostgreSQL 生态更好） - 预计额外 1 周的团队培训时间 ## 参考 - [PostgreSQL vs MySQL 功能对比](...) - [PostGIS 官方文档](...) ``` ## 文件组织 ``` docs/ └── adr/ ├── 0001-use-postgresql.md ├── 0002-adopt-event-driven-architecture.md ├── 0003-choose-react-over-vue.md ├── 0004-implement-cqrs-for-reporting.md ├── 0005-deprecate-rest-in-favor-of-grpc.md └── template.md ``` 命名规则：`NNNN-short-description.md` ## ADR 状态流转 ``` 提议 (Proposed) | v 已接受 (Accepted) -----> 已弃用 (Deprecated) | | v v 已实施 (Implemented) 已替代 (Superseded by ADR-XXX) ``` ## 什么值得记录为 ADR - 技术选型（数据库、框架、语言） - 架构模式（微服务 vs 单体、CQRS、事件驱动） - API 设计决策（REST vs GraphQL、版本策略） - 安全策略（认证方案、加密标准） - 基础设施选择（云厂商、部署方式） **不需要记录**：实现细节、代码风格、小型重构 ## 使用 adr-tools ```bash # 安装 brew install adr-tools # 初始化 adr init docs/adr # 创建新 ADR adr new "Use PostgreSQL as primary database" # -> creates docs/adr/0001-use-postgresql-as-primary-database.md # 替代旧决策 adr new -s 3 "Replace React with Vue for admin panel" # -> creates new ADR and marks 0003 as superseded # 生成目录 adr generate toc > docs/adr/README.md # 生成关系图 adr generate graph | dot -Tpng > docs/adr/graph.png ``` ## 团队工作流 ### 1. 决策讨论阶段 ```markdown # ADR-007: API 版本控制策略 ## 状态 提议中 (2024-03-01) ## 上下文 随着移动端和第三方接入，API 需要支持多版本共存... ``` 提交 PR，团队 review 讨论。 ### 2. 决策确认 PR 合并后将状态改为"已接受"。 ### 3. 定期回顾 每季度检查 ADR 列表： - 哪些需要更新状态？ - 哪些假设已经不成立了？ - 是否需要新的 ADR 来替代旧决策？ ## ADR 评审清单 好的 ADR 应该回答以下问题： 1. **是什么？** — 做了什么决策 2. **为什么？** — 业务或技术驱动力是什么 3. **还考虑了什么？** — 被否决的方案及原因 4. **代价是什么？** — 已知的取舍和技术债 5. **谁决定的？** — 决策者和参与讨论的人 6. **何时决定的？** — 时间上下文很重要 ## 与 RFC 的区别 | 维度 | ADR | RFC | |------|-----|-----| | 长度 | 1-2 页 | 5-20 页 | | 重点 | 决策和理由 | 完整设计方案 | | 时机 | 决策确定后 | 决策讨论前 | | 适用 | 所有架构决策 | 大型跨团队变更 | 两者可以互补：RFC 用于大型决策的讨论，讨论结果记录为 ADR。 ## 实际案例：从 ADR 看架构演进 ``` ADR-001: 使用单体架构（2023-01） ADR-005: 引入消息队列解耦订单处理（2023-06） ADR-009: 拆分用户服务为独立微服务（2024-01） ADR-012: ADR-001 已弃用，全面迁移到微服务（2024-06） ``` 通过 ADR 序列，新人可以理解架构演进的完整历程。 ## 总结 ADR 是团队知识管理的低成本高回报实践。它不需要复杂的工具或流程 — 只需一个 Markdown 文件和一个简单的模板。关键是坚持记录，让每个重要的技术决策都有据可查。当团队成长、成员更替时，ADR 就是你最好的架构记忆。