用 ADR 记录 GCP 云基础设施选型：architecture-decision-record 仓库 Google Cloud Platform 示例深度解读

导读

本文以 architecture-decision-record 仓库中 Google Cloud Platform 架构决策记录示例 为主体，系统拆解一份面向云平台选型的 ADR（Architecture Decision Record，架构决策记录）应该包含哪些章节、每个章节写什么、为什么这样写，并对照仓库内的 Azure、AWS 等同类示例与 Nygard、MADR、Tyree & Akerman 等经典模板，说明如何把"选云平台"这类重大技术决策沉淀为可检索、可审计、可演进的结构化文档。读完本文，你将掌握 ADR 的六段式骨架（Context → Decision → Selections → Rationale → Consequences → Conclusion）及其背后的架构知识管理方法，并能在自己的项目中照此模板落地一份 GCP 选型记录。

一、关联文档是什么：一份典型的云平台选型 ADR

在仓库中，GCP 示例位于 locales/en-001/examples/google-cloud-platform/README.md（同目录下的 index.md 内容与之相同，供网站导航使用）。它与 Azure 云基础设施示例、AWS 示例 并列，构成"多云选型"的对照参考集合。

按照仓库 examples 索引页 的分类，这类文档属于"决策记录示例"（Decision record examples），定位是给团队一个可复制的样板，而非理论说教。这份 GCP 文档的结构是：

这与仓库中 Nygard 模板（Status / Context / Decision / Consequences）以及 MADR 模板（Context and Problem Statement / Considered Options / Decision Outcome / Consequences）的核心思想一致：一份 ADR 的本质是"记录当时为什么做这个决定"，让未来不在决策现场的开发者也能理解"why"，正如仓库 技能文档 所强调的——ADR 的适用场景是"决策具有架构显著性（影响结构、外部接口、质量属性，或难以低成本逆转），且需要被未来开发者理解"。

二、Context：交代决策背景，让记录脱离"马后炮"

原文档的 Context 部分写道：Google Cloud Platform（GCP）是一个主流的云计算平台，提供计算、存储、网络等多种云服务；本 ADR 旨在记录组织为开发与实施基于 GCP 的基础设施所做的架构决策。

这一段的写作要点（可从仓库 suggestions-for-writing-good-adrs 中找到依据）在于：

• 解释组织处境与业务优先级：为什么现在要上云、要选平台，而不是直接跳到"选 GCP"。
• 给出决策动机：让读者明白这不是一次技术炫技，而是响应某类业务诉求。
• 保持简洁：Context 只需两三句话点明问题，详细论证留给后面的 Rationale。

对照参考：Azure 示例 用 Background 章节写明"组织正计划从传统本地机房迁移到云，评估了 AWS、GCP、Microsoft Azure、IBM Cloud 四家供应商"；AWS 示例 则在 Background 中写明"组织快速增长，需要可靠且可扩展的云基础设施"。可以看到，同一类决策记录在不同模板里会用 Background、Context、Problem Statement 等不同小节名表达同一个目的——先立问题，再给答案。

三、Decision：明确"选什么"，并列出评判维度

原文档的 Decision 章节给出了决策结论：组织决定采用 Google Cloud Platform 作为应用的云基础设施，并列出四个主要考量维度：

• Cost-effectiveness（成本效益）
• Scalability（可扩展性）
• Reliability（可靠性）
• Flexibility（灵活性）

这四个词不是空泛的口号，而是后续 Rationale 章节逐一展开论证的"决策驱动因子"。在 MADR 模板中，这种"驱动因子"有专门的 Decision Drivers 小节；在 Tyree & Akerman 模板 中则对应 Assumptions（决策所处的成本、进度、技术等环境假设）。换言之，Decision 章节的最佳实践是"结论 + 评判标准"成对出现，让读者一眼看到"我们依据什么标准选出了这个结果"。

从决策记录质量的角度看，仓库 写作建议文档 还提醒：一份 ADR 应只聚焦一个决策（Specific），并且要写明时间戳（Timestamps），因为成本、进度、规模这类因素会随时间变化——这也是在 Decision 章节值得补充"决策日期、决策者、状态（proposed/accepted/rejected/deprecated）"等元信息的原因，Azure 示例就给出了很好的示范（Decision Title / Decision Maker / Date / Status）。

四、Selections：把大决策拆成具体的服务选型

原文档的 Selections 章节是这份 ADR 最具实操价值的部分，它把"上 GCP"这个大决策细化为四个服务选型：

这种"平台级决策 → 服务级选型"的拆分方式，正是仓库 写作建议文档 所说的"一个大决策往往触发一串后续小决策"（subsequent ADRs）。在本仓库中，你可以找到与之配套的细粒度决策示例：

• 数据库选型：Cloud SQL 是托管关系型数据库，而"选哪种数据库技术"本身就是一个独立决策，见 choosing-a-database-technology 示例（该示例对比了关系型、文档型、事件型三类数据库的适用场景与取舍）。
• 容器编排选型：Compute Engine 上跑容器化应用时，编排层如何选择（Docker Swarm / Kubernetes / Mesos）是另一个典型 ADR 场景，见 Kubernetes 容器编排示例。
• 周边配套决策：密钥管理、环境变量配置、监控告警等都属于"上云后必须回答"的配套问题，仓库中分别有 secrets-storage、environment-variable-configuration、metrics-monitors-alerts 等示例。

实践建议：在复制这份 ADR 到自己的项目时，Selections 章节应补充每个服务的具体规格、配额、区域（region）与可用区（zone）选择、预估用量等信息，让记录从"选了哪些服务"升级为"这些服务以什么形态被使用"。

五、Rationale：四个理由的逐条论证

原文档的 Rationale 章节针对 Decision 中的四个维度给出了论证，这是整份 ADR 的"证据核心"：

• 成本效益（Cost-Effectiveness）：相比其他云平台，GCP 具有较高的成本效益，对预算受限的组织有吸引力。需要注意，原文档在这里给出的是定性结论；仓库 写作建议文档 特别强调"成本、进度、规模"等要素会随时间漂移，因此严谨的做法是在此处附上决策当时的报价对比、预估月度账单并加盖时间戳，未来回看时才能判断该结论是否仍然成立。
• 可扩展性（Scalability）：GCP 易于扩展的基础设施支持实时应对任意规模的流量。这句话的落地方式是明确"垂直扩展（增大实例规格）"与"水平扩展（增加实例数量 + 负载均衡 + 托管实例组自动伸缩）"的具体路径，并给出触发伸缩的指标阈值。
• 可靠性（Reliability）：托管服务具备自动备份与灾难恢复能力，保障资源与数据的高可用。对应到服务层面：Cloud SQL 的自动备份/时间点恢复（point-in-time recovery）、Cloud Storage 的多区域冗余（multi-region）、以及跨可用区/跨区域的部署策略，都是可以在 ADR 中展开的细节。
• 灵活性（Flexibility）：平台横跨 AI、数据分析、物联网等不同领域，具备高度通用性。这呼应了仓库 Azure 示例 中"从 IaaS 到 PaaS 再到 SaaS 的完整服务谱系"这一论证逻辑——云平台的价值之一在于一个供应商覆盖多种业务域，后续迁移 AI/大数据负载时无需更换底座。

为什么 Rationale 是 ADR 的灵魂

仓库 写作建议文档 将 Rationale（解释为什么做这个决策）列为优秀 ADR 的首要特征，建议包含：上下文、各候选方案的利弊（pros and cons）、特性对比、成本/收益讨论等。对照 CSS framework 示例 可以看到更完整的论证形态——它列出了 Semantic UI 与 Bulma 两个候选方案的对比、试点结果、社区反馈，最后才给出结论。也就是说，Rationale 越具体、越带证据（报价、实测、社区反馈），ADR 的可信度与复用价值越高；如果仅仅罗列形容词，这份记录就退化为宣传材料而非决策档案。

六、Consequences：迁移的成本与后续动作

原文档的 Consequences 章节明确指出迁移到 GCP 的三项代价与一个预期收益：

1. 团队培训：需要培训团队掌握 GCP 服务。
2. 应用重构：需要按所选服务重构应用以保持兼容。
3. 基础设施代码改造：需要更新基础设施代码以支持 GCP 服务。
4. 持续成本管理：需要持续管理在 GCP 上配置资源的运营成本。

预期收益：迁移完成后将获得高度可扩展、可靠、成本效益良好的托管基础设施。

这一段在决策记录方法论中的位置非常重要。仓库 写作建议文档 对优秀 Consequences 的定义是：解释做出决策后会发生什么，包括影响、结果、产出、后续跟进事项，并且要包含：

• 后续 ADR 提示：一次大决策通常触发更多小决策（如前文提到的数据库、容器编排、密钥管理、监控告警等），可以在 Consequences 中显式列出"待决策清单"。
• 事后复盘机制：建议团队在决策一个月后回看该 ADR，将记录内容与实际发生的情况对比，用于学习与改进。

在 MADR 模板中，这部分被细分为 Positive Consequences 与 Negative Consequences 两个子节，便于读者快速抓取"好处"与"代价"；而在 Tyree & Akerman 模板 中则对应 Implications 与 Related decisions，强调"决策会带来新需求、新约束、新决策"这一连锁反应。

七、Conclusion：收束记录，但保持开放

原文档的 Conclusion 部分总结：GCP 因其成本效益、可扩展性、可靠性与灵活性，是组织云基础设施的合适选择；通过所选服务组合，可为应用提供高可用且稳健的基础设施。

需要留意的是，仓库 写作建议文档 提出了 ADR 的不可变（Immutable）原则：不要篡改已有记录，而是通过"追加新信息"来修订，或在决策被取代时新建一份 ADR 来 supersede（取代）旧记录。同时 团队协作建议 也提到，实际团队中"可变性"往往比理论上的"不可变性"更实用——可以在原记录中追加带日期的更新说明。因此，Conclusion 不应被视为"盖棺定论"，而应视为这份 ADR 当前状态的一个快照（对应 MADR 模板顶部的Status: proposed | accepted | rejected | deprecated | superseded状态字段）。

八、如何在自己的项目中落地这份 ADR

结合仓库 skills/architecture-decision-record-skill/SKILL.md 与 en-001 总索引 给出的实践路径，落地一份 GCP 选型 ADR 的标准流程是：

1. 判断是否需要 ADR：云平台选型影响结构、外部接口、成本与可逆性，属于典型的"值得记录"的决策。
2. 建立目录：创建adr/或decisions/目录存放记录文件（部分团队偏好decisions/这个词，因为它对非架构决策也开放）。
3. 命名文件：按仓库约定的命名规范——现在时祈使动词短语 + 小写 + 连字符 + .md 扩展名（如adopt-google-cloud-platform.md），如果项目采用编号制则加零填充前缀（如0001-adopt-google-cloud-platform.md）。
4. 套用模板：可直接采用本示例的六段式结构，或参照 Nygard 模板、MADR 模板 等更细化的骨架。
5. 提交到 git：将 ADR 作为普通文本文件纳入版本控制，随代码库演进，未来开发者可回溯决策历史。
6. 持续维护：成本、配额、区域可用性等事实会变化，按时间戳追加更新；当决策被取代时新建新 ADR 并声明 supersede 关系。

九、横向对照：GCP / Azure / AWS 三份云选型 ADR 的写法差异

本仓库同时收录了三份云平台选型示例，非常适合对比学习：

• GCP 示例：六段式（Context / Decision / Selections / Rationale / Consequences / Conclusion），特色是单独设立 Selections 章节，把平台决策拆成服务级选型，实操指向最强。
• Azure 示例：带元信息头（Decision Title / Decision Maker / Date / Status），从"多云评估（AWS、GCP、Azure、IBM Cloud）"的完整背景写起，Rationale 列出 5 条理由（服务全面、可扩展灵活、安全合规、混合云、成本效益），Conclusion 给出明确推荐意见。
• AWS 示例：除决策与背景外，还包含 Considerations（全球数据中心分布、安全框架、按需付费模式）、Ownership（明确云基础设施团队的责任边界）与 Review（年度复审机制）三个特色章节。

三种写法没有优劣之分，差异反映的是团队对决策记录的不同诉求：追求服务落地的看 GCP 版，需要审计与责任归属的参考 AWS 版，重视元信息与合规的可借鉴 Azure 版。你可以在仓库的 examples 总目录 中浏览全部示例，结合团队实际裁剪自己的模板。

十、总结

architecture-decision-record 仓库中的 Google Cloud Platform ADR 示例 是一份结构完整、可直接复用的云平台选型决策记录：它以 Context 立题、Decision 给结论、Selections 落服务、Rationale 讲证据、Consequences 明代价、Conclusion 收记录，完整覆盖了 ADR 方法论要求的"上下文—决策—后果"三要素。将其与仓库内 Azure、AWS 示例及 Nygard、MADR、Tyree & Akerman 模板对照研读，你可以快速掌握一套可迁移的架构知识管理方法，让"为什么选 GCP"这件事不再依赖个人记忆，而是成为团队可检索、可审计、可演进的技术资产。