architecture-decision-record 仓库实战:以 PostgreSQL 数据库选型 ADR 为例解析架构决策记录写法
architecture-decision-record 仓库实战:以 PostgreSQL 数据库选型 ADR 为例解析架构决策记录写法
本篇文章以开源仓库 architecture-decision-record 中收录的示例文档 PostgreSQL 数据库选型 ADR 为核心骨架,完整还原其 Context、Decision、Justification、Alternatives、Conclusion 五个部分的决策记录写法,并结合仓库内的 ADR 基础概念文档、写作规范、模板与技能(Skill)说明,给出可直接复用的数据库选型 ADR 撰写清单。读完本文,你将掌握 ADR 的标准结构、理由论证方法、文件命名与状态管理规则,并能参照仓库中的 40 个示例为自己的项目写出同样规范的决策记录。
一、先理解 ADR:这篇文档在记录什么
在拆解 PostgreSQL 选型示例之前,需要先明确 ADR 的定义。仓库的 what-is-an-architecture-decision-record 给出了权威解释:
- Architecture Decision Record (ADR):记录一次重要架构决策及其上下文(Context)和后果(Consequences)的文档;
- Architecture Decision (AD):为满足一项重要需求而做出的软件设计选择;
- Architecture Decision Log (ADL):某个项目(或组织)创建并维护的全部 ADR 的集合;
- Architecturally-Significant Requirement (ASR):对软件系统架构产生可度量影响的需求;
- 上述概念都属于 Architecture Knowledge Management (AKM) 的范畴。
本仓库以 locales/en-001 为内容源(source of truth),其余语言均为其翻译,这一点在 spec/content.md 中有明确说明。示例文档统一存放在 locales/en-001/examples/ 目录下,其中 "Specific databases" 分组收录了 MySQL database 和 PostgreSQL database 两个数据库选型 ADR,我们分析的对象正是后者。
二、原文档全文解读:PostgreSQL 数据库选型 ADR
示例文档 README.md 的标题为 Architecture Decision Record: PostgreSQL database,记录的决策标题是 Use of PostgreSQL Database(采用 PostgreSQL 数据库)。它包含五个标准部分,下文逐一翻译并解读。
Context(背景)
Our organization is currently evaluating options for the most suitable database management system to be used in our upcoming project. We have narrowed our search down to two options – PostgreSQL and MySQL. After careful consideration, we have decided to use PostgreSQL due to its advanced features and performance capabilities.
组织正在为即将启动的项目评估最合适的数据管理系统(DBMS),候选方案缩小到 PostgreSQL 与 MySQL 两个选项,经过仔细考量后决定采用 PostgreSQL。
从 ADR 写法看,这段 Context 交代了三个关键信息:决策主体(组织的某个新项目)、候选范围(已收敛到两个选项)、初步倾向及原因(高级特性与性能)。这符合仓库 suggestions-for-writing-good-adrs 中对 Context 的要求——说明组织的实际处境与业务优先级,而不是只写一句"我们需要一个数据库"。
Decision(决策)
We will use PostgreSQL as the preferred database management system for our organization's upcoming project.
决策内容非常直白:将 PostgreSQL 作为本项目首选数据库管理系统。仓库 Skill 的书写指南强调,Decision 部分应"plainly state the chosen direction, not hedge"(直截了当地陈述所选方向,不要含糊其辞),这个示例正是如此。
Justification(理由论证)
这是整篇 ADR 信息密度最高的部分,原文给出了五条理由,必须完整保留:
- 高级特性(Advanced features):PostgreSQL 具备丰富的进阶能力,包括 JSON 支持、全文检索(full-text search)和空间数据管理(spatial data management),这些对本项目必不可少;
- 性能(Performance):PostgreSQL 有经过验证的出色性能表现,可确保项目顺利运行而不出现性能问题;
- 社区支持(Community support):PostgreSQL 拥有庞大且活跃的社区,能持续提供更新与支持,便于在开发阶段快速解决问题;
- 可扩展性(Scalability):PostgreSQL 高度可扩展,能轻松处理大量数据,这对本项目至关重要;
- 安全性(Security):PostgreSQL 具备健壮的安全机制,可时刻保障项目数据安全,满足组织的全部安全要求。
这五条理由分别对应功能、性能、生态、规模、安全五个维度,构成了一个完整的数据库选型评估框架。值得注意的是,仓库的写作建议要求"State pros and cons in terms that align with this team's actual needs and goals"——理由应当贴合团队真实需求而非套话,读者在复用此示例时,应把每条理由替换成自己项目的具体场景(例如明确"JSON 支持"具体服务于哪类数据形态、全文检索用于哪个搜索功能)。
Alternatives(备选方案)
The other option that we considered was MySQL. MySQL is also a highly capable database management system, but it lacks some of the advanced features that PostgreSQL offers, and its performance capacity is not as good as that of PostgreSQL.
备选方案是 MySQL:它同样是能力很强的数据库管理系统,但缺少 PostgreSQL 的一些高级特性,性能能力也不及 PostgreSQL。
需要说明的是,这是该 ADR 文档自身的结论性表述,属于决策记录中的判断理由,而非本文对两款数据库的客观定论。作为对照,仓库中另一篇 MySQL 数据库选型 ADR 则给出了完全相反的决策(选择 MySQL),它列出 MySQL、PostgreSQL、Oracle、Microsoft SQL Server、MongoDB 五个候选,并分别记录 Positive / Negative Consequences——两篇示例放在一起,恰好演示了"同一类决策在不同组织背景下可以得出不同结论"的 ADR 本质。
Conclusion(结论)
Based on our analysis, we have decided to use PostgreSQL as the preferred database management system for our upcoming project. This decision has been made after careful consideration, and we believe that it will help us achieve our project goals efficiently and effectively.
结论重申了决策,并强调该决定经过审慎考量,相信能高效、有效地达成项目目标。文末还带有一行脚注 Credit: this page is generated by ChatGPT, then edited for clarity and format.,说明这是 AI 生成后经人工编辑整理的示例,这一点也在 examples/README.md 的分类注释("ChatGPT examples")中得到印证。
三、为什么"理由"是 ADR 的灵魂:仓库给出的写作标准
PostgreSQL 选型示例 之所以成立,核心在于 Justification 部分完整回答了"为什么选它"。仓库文档 suggestions-for-writing-good-adrs 将这一原则系统化为四条 ADR 质量特征:
- Rationale(理由):解释做出该决策的原因,可包含背景、各候选方案的优缺点、特性对比、成本/收益讨论等——本示例的五条 Justification 正是这一特征的标准示范;
- Specific(聚焦):每篇 ADR 只记录一个决策,不要把多个决策塞进同一文档;
- Timestamps(时间戳):标明每条信息的写入时间,对成本、排期、扩展规模等随时间变化的要素尤其重要;
- Immutable(不可变):不要改写 ADR 中已有信息,需要更新时应追加带日期的新信息,或用新建 ADR 取代旧 ADR。
Skill 的写作指南 writing-guide.md 还补充了 Consequences 部分的写法:既要写"什么变得更简单",也要写"什么变得更困难",并标注该决策触发的后续 ADR。需要指出的是,本示例缺少独立的 Consequences 部分(决策的长期影响分散在 Justification 与 Conclusion 中),这是它在写法上的一个可改进点——读者在自己的 ADR 中应补上"选择 PostgreSQL 后团队需要学习新技能 / 迁移成本 / 运维复杂度"这类正反后果,使记录更加完整。
四、从示例到实践:如何在你的项目写出同样的数据库选型 ADR
仓库自带的 architecture-decision-record-skill 给出了完整的实操流程,结合本示例可总结为以下步骤。
步骤 1:判断该决策是否值得写 ADR
Skill 的建议是:当决策具有架构意义(影响系统结构、外部接口、质量属性,或难以低成本逆转)、需要未来开发者理解"为什么"、涉及值得记录的权衡时,才需要 ADR。数据库选型恰好同时满足三条:它决定数据层架构、影响所有业务模块、迁移成本高——因此几乎必然值得记录,正如仓库中的两篇数据库 ADR 示例所示。
步骤 2:建立决策目录
mkdir decisions
# 或使用 adr/
Skill 提到,有些团队偏好 decisions/ 目录名,因为 "architecture" 一词和 "ADR" 缩写会让部分成员望而生畏,而 "decisions" 能吸引团队写入更多类别的决策(供应商选择、排期决策等)。
步骤 3:按命名规范创建文件
仓库文档 file-name-conventions-for-adrs 规定了一套命名约定,本示例对应的文件名应为:
choose-postgresql-database.md
规范要点:使用现在时祈使动词短语(便于阅读且与提交信息格式一致)、小写加连字符、.md 扩展名。若项目采用编号制,可加零填充序号前缀,如 0007-choose-postgresql-database.md。
步骤 4:选择模板并填充内容
Skill 的模板速查表(templates.md)建议默认使用 Michael Nygard 模板——它最简单、最广为认可,本示例的结构与之高度吻合:
# Title
## Status
What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?
## Context
What is the issue that we're seeing that is motivating this decision or change?
## Decision
What is the change that we're proposing and/or doing?
## Consequences
What becomes easier or more difficult to do because of this change?
仓库中收录了 Nygard 模板原文。此外还有 MADR、Tyree & Akerman、Business case、Alexandrian pattern、Planguage、EdgeX、arc42、Gareth Morgan、GIG Cymru NHS Wales、ITD 等十余种模板可供选择;若想强化选项对比,MADR 模板(含 Considered Options 与 Pros and Cons)会比本示例的写法更完整。
步骤 5:标注状态与时间戳
Skill 建议为每条 ADR 标注状态:
Status: proposed | accepted | rejected | deprecated | superseded by <link>
本示例未显式写出 Status 字段,默认可视为 "accepted"。同时按写作规范为文档标注日期,因为数据库厂商定价、版本能力等信息会随时间变化。
步骤 6:处理决策被取代的情形
当新决策取代旧决策时(例如未来从 PostgreSQL 迁移到新数据库),按 Skill 的流程执行:
- 新建一篇描述新决策的 ADR 文件;
- 将旧 ADR 的 Status 更新为
Superseded by new-adr; - 在新 ADR 的 Status/Links 中反向链接
Supersedes old-adr。
此外,一次大的数据库选型往往会触发后续 ADR——例如连接池选型、备份策略、读写分离方案等,这正是仓库写作建议中"one ADR often triggers the need for more ADRs"的典型场景。
五、仓库中的关联资源:对比与纵深
围绕这篇 PostgreSQL 选型 ADR,仓库还提供了可直接对照学习的资源:
- MySQL 数据库选型 ADR:同主题的反向决策示例。它列出决策考量因素(易用性、社区支持、性能与扩展性、安全与可靠性、成本与许可、技术栈兼容性)、五个候选方案(MySQL、PostgreSQL、Oracle、Microsoft SQL Server、MongoDB),并把后果拆分为 Positive / Negative 两部分——与 PostgreSQL 示例形成互补,展示 ADR 写法的两种风格;
- 选择数据库技术 ADR:提供更宏观的分类视角——关系型数据库(MySQL、PostgreSQL、Oracle)、文档型数据库(MongoDB、Couchbase、DynamoDB)与事件型数据库(Kafka、Pulsar、AWS Kinesis)——其中明确将 PostgreSQL 归入关系型数据库,并指出关系型数据库适合需要复杂数据关系与事务的应用,可作为理解本示例选型逻辑的背景材料;
- 示例索引:展示全部 40 个示例的组织方式,数据库示例位于 "Specific databases" 分组;仓库根 README.md 也列出了 Examples 入口;
- 多语言镜像:本示例已同步到
ar-001、bn-001、de-001、fr-001、ja-001、zh-001、zh-tw等 30 余个语言目录,spec/content.md 规定产品名(如 PostgreSQL)在任意语言中均保持拉丁拼写,代码块与 URL 不翻译; - 网站版:
architecture-decision-record.github.io目录下的 index.md 等页面由静态站点脚本生成,generate-llms.mjs、generate-sitemap.mjs 等脚本负责把 locales 内容转换为可检索的站点与llms.txt,便于搜索引擎和 AI 检索。
六、结语
PostgreSQL 数据库选型 ADR 虽然篇幅简短,却完整示范了一篇合格 ADR 的核心要素:清晰的 Context、不含糊的 Decision、结构化多维度论证的 Justification、明确的 Alternatives 与收束的 Conclusion。结合仓库的写作规范与 Skill 流程,你可以把它作为模板骨架,替换为自己的项目背景与理由,写出一篇同样规范、可被未来开发者与 AI 检索工具理解的数据库选型决策记录。最后提醒一点:仓库根 README 明确建议 "Do your own due diligence for these resources before using them in any critical systems"——示例中的结论是决策记录内容而非推荐基准,落地前请基于自身场景独立验证。