架构决策记录概览

Last reviewed 2023-04-11 UTC

您可以使用架构决策记录 (ADR) 帮助说明基础架构或应用团队选择特定设计的原因。本文档介绍了在 Google Cloud 上构建和运行应用时何时以及如何使用 ADR。

ADR 会捕获可用的关键选项、推动决策的主要要求以及设计决策本身。通常将 ADR 存储在靠近与该决策相关的代码库的 Markdown 文件中。如果有人需要了解特定架构决策的背景，例如使用区域 Google Kubernetes Engine (GKE) 集群的原因，则可以查看 ADR 以及关联代码。

ADR 还可以帮您运行更可靠的应用和服务。ADR 可帮您了解当前状态以及在出现问题时进行问题排查。ADR 还会构建一组工程决策，以帮助做出未来的决策选择和部署。

何时使用 ADR

您可以使用 ADR 来跟踪您认为对部署很重要的关键区域。您的 ADR 中可能包含以下类别：

  • 特定产品选择，例如在 Pub/Sub 和 Pub/Sub Lite 之间进行选择。
  • 特定产品选项和配置，例如将区域 GKE 集群与多集群 Ingress 搭配使用以实现高可用性应用。
  • 常规架构指南，例如 Dockerfile 清单的最佳做法。

由于以下选择，某些具体实例可能会提示您创建 ADR：

  • 如何以及为何为 Cloud SQL 实例设置高可用性 (HA)？
  • 您如何处理 GKE 集群的正常运行时间？您是否使用区域级集群？您是否使用 Canary 版本？请说明原因。

在您评估要使用的产品时，ADR 有助于解释您的每个决策。您可以在团队不断发展的同时，重新审视 ADR，并详细了解栈以及制定或调整其他决策。如果您进行了调整，请添加之前的决策和进行更改的原因。此历史记录会记录架构如何随业务需求的变化而变化，或者存在新的技术要求或可用解决方案的情况。

以下提示可帮助您了解何时创建 ADR：

  • 当您遇到技术挑战或问题，并且没有现有的决策依据时，例如推荐的解决方案、标准操作程序、蓝图或代码库。
  • 当您或您的团队提供的解决方案没有记录在团队可访问的某个位置时。
  • 当有两个或更多工程选项，并且您想记录您的想法和选择背后的原因时。

在写入 ADR 时，考虑到潜在读者会很有帮助。主要读者是指研究 ADR 所涵盖技术的团队成员。更广泛的 ADR 潜在读者群体可能包括希望了解您的决策的相邻团队，例如架构和安全团队。

您还应该考虑应用可能会更改所有者或添加新的团队成员。ADR 可帮助新贡献者了解所做的工程选择的背景。ADR 还可以让您更轻松地规划未来的更改。

ADR 的格式

典型的 ADR 包含一组章节。您的 ADR 应该有助于捕获您认为对应用和组织非常重要的内容。某些 ADR 可能是一页说明，而其他 ADR 则需要更长的说明。

以下示例 ADR 概览演示了如何设置 ADR 的格式，使其包含对环境很重要的信息：

  • 作者和团队
  • 您要解决的上下文和问题
  • 您要满足的功能和非功能要求
  • 决策影响的潜在关键用户历程 (CUJ)
  • 密钥选项概览
  • 您的决策和接受选择背后的原因

为了帮助保留决策记录，您可以为每个决策添加时间戳，以显示做出选择的时间。

ADR 的工作原理

当工程师、开发人员或应用程序所有者可以轻松访问其包含的信息时，ADR 的效果最佳。当他们想要了解为什么以某种方式完成某项操作时，可以查看 ADR 寻找答案。

为了使 ADR 可访问，一些团队将其托管在企业主也可以访问的中央 wiki 中，而不是在他们的源控制存储库中。当有人对具体的工程决策有疑问时，ADR 可以提供答案。

ADR 在以下场景中运行良好：

  • 新手入门：新的团队成员可以轻松了解项目，并且在查看应用代码或其他实现时如果有疑问，可以查看 ADR。
  • 所有权切换：如果团队之间存在技术栈的转移，则新的所有者可以审核以往的决策以了解当前状态。ADR 还有助于避免重复相同的讨论点，或者在了解历史上下文的情况下重新访问未来的主题。
  • 对齐：当 ADR 详细说明为什么做出某些决定和决定反对的替代方案时，团队可以在整个组织的最佳做法上对齐。

ADR 通常用 Markdown 编写，使其保持轻量级和基于文本。Markdown 文件可以与应用代码一起包含在源代码控制代码库中。

将 ADR 存储在您的应用代码附近，最好存储在同一个版本控制系统中。对 ADR 进行更改时，您可以根据需要从源代码控制系统查看以前的版本。

您还可以使用其他媒介，例如共享的 Google 文档或内部 Wiki。非 ADR 团队的用户可能更容易访问这些备用位置。另一种方法是在源代码控制代码库中创建 ADR，但将关键决策镜像到更易于访问的 Wiki 中。

后续步骤