企业官网建设流程全解析

导读：本文以开源仓库 architecture-decision-record 中locales/en-gb/examples/postgresql-database这一份真实 ADR 示例文档为骨架，系统讲解"数据库选型类架构决策"应如何记录：从背景、决策、论证、备选方案到结论的完整写作范式，并深入结合仓库内的模板、写作规范、多语言镜像结构与配套 Agent Skill，帮助你直接复用这套方法论，为自己的项目写出一份高质量、可被团队与 AI Agent 检索引用的数据库选型 ADR。

一、这份示例文档在仓库中的定位

architecture-decision-record 是一个以"架构决策记录（Architecture Decision Record, ADR）"为核心的开源知识仓库，汇集了大量模板、示例与教程。其中locales/en-gb/examples/目录收录了各类真实场景的 ADR 示例，本文的主角 PostgreSQL 数据库示例 就是其中之一，与其配套的还有 MySQL 数据库示例、数据库技术选型示例 等，共同构成一组"数据库决策"主题的参考素材。

从仓库结构看，这份示例具有几个值得注意的特点：

• 同一内容以多语言镜像存在：仓库遵循"英文在locales/en-001编辑、再翻译到其他语言"的约定（见 AGENTS.md），因此 PostgreSQL 示例同时存在于 en-001 版本（美式拼写 organization）与 en-gb 版本（英式拼写 organisation），并已翻译为简体中文版 postgresql数据库。
• README 与 index 内容一致：按仓库约定，每个内容目录中的README.md是index.md的符号链接，编辑时只需维护index.md。
• 标注了内容来源：文档末尾注明 "Credit: this page is generated by ChatGPT, then edited for clarity and format."，说明这是一份 AI 辅助生成、人工润色后的示例，适合作为写作范式参考，但如仓库 README 的提示所言，用于关键系统前仍需自行尽职调查（do your own due diligence）。

二、原文档核心内容完整拆解：一篇数据库选型 ADR 的标准写法

这份 PostgreSQL 示例遵循了简洁的 ADR 结构：标题（Title）→ 背景（Context）→ 决策（Decision）→ 论证（Justification）→ 备选方案（Alternatives）→ 结论（Conclusion）。下面逐节继承原文内容并展开讲解其写法意图。

2.1 标题与背景（Context）

原文档以两行开头点明主题：

# Architecture Decision Record: PostgreSQL database Title: Use of PostgreSQL Database

随后是背景部分：组织正在为即将启动的项目评估最合适的数据库管理系统，候选范围缩小到 PostgreSQL 与 MySQL 两个选项，经过慎重考虑，倾向于选择 PostgreSQL。

写作要点：好的 Context 应说明"组织当下的实际处境与业务优先级"，而不只是罗列技术问题（参见 写作建议文档）。这里明确交代了"即将开展新项目、需要选型 DBMS、候选已收敛为两项"三个关键信息，让读者立刻理解决策的触发场景。

2.2 决策（Decision）

原文档的决策表述非常简洁直接：

We will use PostgreSQL as the preferred database management system for our organisation's upcoming project.

即"将 PostgreSQL 作为组织即将开展项目的首选数据库管理系统"。写作要点是：决策句应"明确陈述所选方向，不要含糊其辞"，这正是仓库 ADR Skill 中强调的 "Decision should state the chosen direction plainly, not hedge"。

2.3 论证（Justification）：五大理由逐一展开

原文档给出了选择 PostgreSQL 而非 MySQL 的五个理由，这是整篇 ADR 最有分量的部分，下面逐条继承并补充说明其在真实项目中的含义：

1. 高级功能（Advanced features）：PostgreSQL 具备广泛的高级特性，如JSON 支持、全文搜索（full-text search）、空间数据管理（spatial data management），对项目至关重要。展开来看：JSON/JSONB 类型让 PostgreSQL 能同时胜任关系型与半结构化数据场景；内置全文检索减少了额外引入搜索引擎组件的必要；PostGIS 等空间扩展覆盖地理数据需求。这三项能力直接回应了"单一数据库承载多样化数据需求"的选型诉求。
2. 性能（Performance）：PostgreSQL 在性能方面有良好的实践记录，能保障项目平稳运行、避免性能问题。对这类表述，写作时建议在 ADR 中补充可量化的证据（压测数据、业务峰值预估），正如写作指南所强调的：凡是会随时间变化的信息（成本、排期、扩展性数据）都应打上时间戳。
3. 社区支持（Community support）：PostgreSQL 拥有庞大而活跃的社区，定期发布更新并提供支持，便于在项目开发阶段解决各类问题。这一点直接关系到团队的实际运维风险：活跃社区意味着更及时的安全补丁、更丰富的文档与第三方工具生态。
4. 可扩展性（Scalability）：PostgreSQL 可扩展性强，能轻松承载大量数据。这呼应了项目对数据规模增长的预期，也是选择"能长期演进"的数据库的关键考量。
5. 安全性（Security）：PostgreSQL 具备稳健的安全机制，可确保项目数据始终处于受保护状态，满足组织全部安全要求。涉及数据合规、权限管理、审计等场景时，这一条往往是决策的硬性门槛。

2.4 备选方案（Alternatives）

原文档如实记录了被否决的选项：MySQL。表述客观克制——MySQL 同样是能力很强的 DBMS，但缺少 PostgreSQL 的部分高级特性，性能容量也逊色一些。

写作要点：ADR 的价值在于"记录被放弃的选项及其放弃理由"。仓库中同主题的 MySQL 数据库示例 从 MySQL 视角给出了另一种范式：它明确列出Decision Considerations（易用性、社区支持、性能与扩展性、安全与可靠性、成本与许可、技术栈兼容性）和Considered Options（MySQL、PostgreSQL、Oracle、SQL Server、MongoDB），再给出决策结果与正反面后果（Consequences）。两篇对照阅读，可以清晰看到"同一决策主题、两种记录深度"的写法差异：PostgreSQL 示例是精简的论证式，MySQL 示例是完整的选项对比式。

2.5 结论（Conclusion）

原文档以结论收尾：基于上述分析，决定采用 PostgreSQL 作为首选 DBMS，并相信该决策能高效有效地支撑项目目标达成。结论与决策首尾呼应，形成完整闭环。

三、把这份示例套用到你的项目：实操落地指南

3.1 文件命名与目录约定

仓库在 文件命名约定文档 中给出了明确规范，也体现在 ADR Skill 中：

• 文件名使用现在时祈使动词短语，如choose-database.md、format-timestamps.md；
• 使用小写 + 连字符（与仓库自身命名一致）；
• 扩展名为.md；
• 若项目采用编号制，可加零填充序号前缀，如0007-choose-database.md（adr-tools 风格）。

3.2 用 git 管理 ADR 的最小流程

仓库的 如何使用 git 开始 ADR 给出了最简实践：

# 创建存放 ADR 的目录 mkdir adr # 为每条决策创建一个文本文件，例如 choose-database.md vi adr/choose-database.md # 写入任意你认为必要的内容（可参考仓库中的模板） # 提交到 git 仓库 git add adr/choose-database.md && git commit -m "Add ADR: choose database"

如果还没有既定约定，ADR Skill 建议优先使用顶层decisions/或adr/目录；有些团队偏爱decisions这个词，因为它比缩写 "ADR" 更容易被接纳，也更鼓励把供应商决策、规划决策等一并纳入同一套模板。

3.3 选择模板：这篇示例对应哪种范式？

本文的 PostgreSQL 示例结构（Context → Decision → Justification → Alternatives → Conclusion）非常接近经典的 Michael Nygard 模板（Title、Status、Context、Decision、Consequences）的变体。仓库的 Skill 提供了模板速查表：

其中 MADR 模板 特别适合数据库选型这类"多选项对比"决策——它同时提供精简版与强调"选项及利弊"的详尽版。

3.4 写作自检清单（来自仓库规范）

综合 写作建议文档 与 写作指南，写一篇数据库选型 ADR 时应自查：

• 有理由（Rationale）：说明决策动机，包括背景、各选项的利弊、功能对比、成本收益讨论——这正是本文 2.3 节论证部分的价值所在；
• 单一决策（Specific）：一份 ADR 只记录一个架构决策，不要捆绑多个独立决策；
• 带时间戳（Timestamped）：成本、排期、扩展性等易变信息标注日期；
• 默认不可变（Immutable）：已接受的 ADR 不改写原文，而是追加带日期的补充信息，或用新 ADR 取代旧 ADR；
• 给状态（Status）：为记录标注proposed / accepted / rejected / deprecated / superseded by <link>；
• 后果双面性（Consequences）：既写"变得更容易的"，也写"变得更困难的"，并指出该决策是否触发后续 ADR（例如选型 PostgreSQL 后，可能还需要"连接池方案""备份策略"等子决策）。

四、进阶：让数据库选型决策"可被验证、可被 AI 检索"

4.1 把决策变成可测试的代码：Fitness Functions

仓库在 决策适应度函数文档 中提出了一个重要理念：决策记录（decision record）文档化决策，而适应度函数（fitness function）用自动化代码持续验证决策被执行。

对应到数据库选型场景，可以这样设计：

• 示例决策："我们使用 PostgreSQL 作为主数据库"；
• 示例适应度函数：在 CI 中自动检查项目配置、连接串、迁移脚本均指向 PostgreSQL，且禁止出现 MySQL 专属方言的 SQL。

这类检查可以用 ArchUnit（Java）或 ArchUnitTS（TypeScript/JavaScript）实现，让"选型 PostgreSQL"从一句文档声明变成每次构建都会执行的硬性规则。

4.2 仓库自带 AI 协作能力：Claude Code Skills

本仓库在 skills/ 下提供了两个可直接复用的 Agent Skill：

• architecture-decision-record-skill：通用技能，帮助任何项目判断"该决策是否需要 ADR"、建立adr/或decisions/目录、命名文件、从十一种内置模板中选择合适骨架，并写好 Context / Decision / Consequences 段落；
• architecture-decision-record-maintainer-skill：面向本仓库维护者，记录仓库布局、README/locales 镜像约定，以及新增模板、示例、工具链接的步骤。

使用方式：将对应文件夹复制到目标仓库的.claude/skills/目录（或~/.claude/skills/以全局可用），然后让 Claude Code 依据这些技能撰写或评审 ADR。这意味着本文介绍的这套 PostgreSQL 选型 ADR 写法，可以直接通过自然语言指令让 AI 助手复现——例如"按仓库规范为我们的数据库选型写一份 ADR"。

4.3 在仓库中继续深挖

如果你想查看更多同类素材，建议依次阅读：

• 示例索引：其中"Specific databases"分类下并列列出 MySQL 与 PostgreSQL 两篇数据库示例；
• MySQL 数据库示例：同一主题的反向视角，含完整的"决策考量 + 候选选项 + 正负后果"结构；
• 数据库技术选型示例：更宏观地对比关系型、文档型、事件型三类数据库，可帮助你判断"是否真的需要关系型数据库"这一前置问题；
• Nygard 模板 与 MADR 模板：把示例结构还原为可直接套用的空白骨架。

五、总结：从一份示例到一套可复用的选型决策方法

回顾整篇 PostgreSQL 数据库 ADR 示例，它用最精简的篇幅演示了数据库选型决策记录的完整闭环：背景交代触发场景，决策一句话定方向，论证给出五条可辩护的理由，备选方案如实记录被否决的 MySQL，结论与决策呼应收束。结合仓库的模板体系、命名规范、写作指南、fitness function 思想与 Agent Skill，这套方法论可以直接迁移到任何团队的数据库选型乃至更广泛的技术决策中——让每一个"为什么选它"都能被未来的开发者、审计者和 AI 轻松理解与引用。