架构决策记录 ADR

在项目和产品开发过程中，软件工程团队需要做出架构决策以实现其目标。这些决策可以是技术性的，也可以与流程相关。

技术决策：例如决定使用JBOSS Data Grid作为缓存解决方案还是选择Amazon Elasticache，或者决定使用AWS Network Load Balancer (NLB) 而不是 AWS Application Load Balancer (ALB)。

流程决策：决定使用内容管理门户来分享文档或与项目相关的工件。做出这些决策是一个既耗时又困难的过程，团队有必要为这些决策提供理由、进行记录，并与相关的利益相关者进行沟通。

在做出架构决策时，常常出现三大反模式：

出于对做出错误选择的恐惧，根本没有做出决策。
做出决策时没有任何理由，大多数时候，人们不明白为什么做出这样的决策，以及已经考虑了哪种用例或场景。这导致同一主题被多次讨论。
决策没有被记录在架构决策仓库中，因此团队成员忘记或不知道已经做出了这个决策。

什么是ADR？

架构决策记录（ADR）是一份文档，用于记录决策，包括决策是如何做出的背景以及采纳该决策的后果。

何时撰写ADR？

当需要做出重要的架构决策时，通常会编写ADR，例如选择新的技术、框架或设计模式，或者在不同的架构目标（如性能、可扩展性和可维护性）之间做出权衡。

ADR也对记录已经做出的决策非常有用，以确保开发团队的所有成员都明白其背后的原因。ADR还确保你与组织的IT策略保持一致。

ADR通常包括诸如正在解决的问题、已考虑的选项、已做出的决策、决策背后的原因以及任何相关的技术细节等信息。它们还可能包括与决策相关的任何含义或风险，以及由于决策可能需要的任何未来工作。

撰写ADR可以帮助促进开发团队内的透明度和协作，同时为将来可能需要了解过去决策背后原因的开发者提供有价值的资源。

撰写ADR时的最佳实践

编写架构决策记录（ADR）时，遵循一些最佳实践是很重要的，以确保ADR清晰、有用且易于理解。以下是撰写ADR的一些建议：

从清晰的标题开始：ADR的标题应该简洁明了，总结所做的决策。
定义问题：首先明确定义决策要解决的问题或挑战。这有助于为决策提供上下文，并确保每个人都理解要解决的问题。
描述决策：清晰地描述已做出的决策，包括已考虑的替代方案以及选择所选选项的原因。这应该包括做出的任何权衡或妥协，以及任何相关的技术细节。
解释理由：提供决策背后的原因的清晰、详细的解释。这应包括任何相关的业务或技术考虑，以及任何风险或潜在缺陷。
记录任何影响：记录决策的任何影响，包括对系统的其他部分的任何依赖性、对性能或可扩展性的任何影响，以及由于决策可能出现的任何风险或问题。
保持简洁：ADR应该简洁且易于阅读。避免包括不必要的信息或技术术语，专注于提供决策过程及其背后原因的清晰和简洁的解释。
保持最新：随着项目的进展，应保持ADR的更新。如果出现影响决策的新信息或考虑因素，应更新ADR以反映这些变化。

遵循这些最佳实践，ADR可以提供重要架构决策的清晰和有用的记录，并帮助确保团队中的每个人都了解这些决策背后的原因。

示例ADR

既然我们已经定义了什么是ADR以及编写ADR时应遵循的最佳实践，那么现在让我们尝试按照这些最佳实践来编写一个ADR。

为了编写一个示例ADR，我们将尝试记录博客中描述的一个解决方案，即从本地存储迁移非结构化数据（文件）到AWS。在该博客中，有三种情境及每种情境的解决方案。对于这个ADR示例，我们将选择使用AWS DataSync从NAS迁移到AWS的解决方案。

标题：使用AWS DataSync从NAS迁移到AWS

状态：已接受 

日期：2023年10月6日 

背景：
应用程序A从应用程序X接收文件，处理它们并生成大小在50-300 GB之间的数据文件。然后，这成为另一个应用程序Y要使用的输入。通过NFS存储，所有三个应用程序可以访问这些数据。应用程序A正在迁移到AWS，而应用程序X和Y继续在本地运行。我们使用AWS弹性文件系统（EFS）在AWS上替代NFS。但这使得应用程序难以从共同的存储解决方案中读/写，而且网络延迟减慢了应用程序X和应用程序Y的速度。

决策：
我们将使用AWS DataSync服务进行初步迁移，将近1 TB的数据从本地NFS存储迁移到AWS EFS。
AWS DataSync可以在任何两个网络存储或对象存储之间传输数据。这些可以是网络文件系统（NFS）、服务器消息块（SMB）文件服务器、Hadoop分布式文件系统（HDFS）、自管理对象存储、AWS Snowcone、Amazon简单存储服务（Amazon S3）桶、Amazon弹性文件系统（Amazon EFS）文件系统、Amazon FSx for Windows文件服务器文件系统、Amazon FSx for Lustre文件系统和Amazon FSx for OpenZFS文件系统。
为了满足应用程序从共同的存储解决方案中读/写的需求，并解决在Direct Connect中读/写操作过程中涉及的网络延迟，我们安排在NFS和EFS之间使用AWS DataSync服务定期同步特定的输入和输出文件夹。这意味着所有三个应用程序在同步完成后查看的文件集都是相同的。

后果：

积极的 
• 无固定/预付费用，只需为数据传输的每千兆字节（GB）支付0.0125美元。

消极的
• 同步可以安排为最少一小时一次。这个软限制可以修改为最多15分钟一次，但这会导致性能问题和后续的同步计划被排队，形成一个循环。
• 双向同步被配置为排队方式运行。也就是说，一次只能执行一个方向的同步。应用程序在同步间隔完成后必须读取文件。在我们的情况下，文件每天只生成一次，所以我们通过及时安排读/写来缓解了这个问题。
• AWS DataSync Agent（虚拟设备）必须在本地的专用VM上安装。

合规性：

备注：

作者：Rakesh Rao 和 Santhosh Kumar Ramabadran

版本：0.1

变更日志：0.1：最初提议的版本

尽管上面是一种格式，但与利益相关者达成协议后，ADR可以采用任何格式创建。它可以简单到Word文档、电子表格或演示文稿。

何时不编写ADR？

尽管架构决策记录（ADRs）可以帮助记录重要的架构决策，但在某些情况下，编写ADR可能是不必要或不适当的。以下是一些例子：

次要决策：如果一个决策对系统的架构影响很小或相对简单，可能不需要编写ADR。例如，如果团队决定将一个库更新到新版本，并且预计此更新对整体架构的影响很小，那么可能不需要ADR。
临时决策：如果一个决策预计是暂时的，或只适用于特定的背景或情境，可能不需要编写ADR。例如，如果团队决定为一个错误实现一个临时的解决方法，而这个解决方法预计不会成为长期的解决方案，那么可能不需要ADR。
常规决策：如果团队作出的决策是常规性的，不特别重要或需要很少的讨论或辩论，那么可能不需要ADR。例如，如果团队决定遵循一个既定的设计模式或使用一种常用的技术，那么可能不需要ADR。
现有文档：如果决策已在其他地方记录，如项目要求或设计文档中，则可能不需要为该决策专门创建ADR。

最终，是否编写ADR的决策取决于决策的重要性和它被做出的背景。如果决策对系统的架构有重大影响、涉及权衡或替代方案、或可能有长期影响，通常建议创建ADR来记录决策过程。

ADR的替代方案

虽然架构决策记录（ADRs）是记录重要架构决策的常见和有效方法，但根据项目的特定背景和需求，还有几种替代方法。以下是几种替代ADR的方法：

代码注释：与ADRs的一个简单替代方法是在代码库中直接使用代码注释来记录架构决策。这对于较小的项目或那些更喜欢轻量级文档方法的团队来说可能是一个有用的方法。但是，代码注释可能变得难以管理，并且对于更复杂的决策可能不提供足够的背景或详细信息。
设计文档：设计文档可以提供一种更全面和详细的方法来记录架构决策。这些文档可以包括图表、流程图和其他视觉辅助工具来帮助解释系统的架构。然而，设计文档可能需要大量时间来创建，并可能随着项目的发展而过时。
Wiki或知识库：与ADR相比，Wiki或知识库提供了一种更灵活和可搜索的方式来记录架构决策。对于大型或复杂的项目，这种方法特别有用，因为它允许团队轻松找到并参考与特定架构决策相关的信息。但是，Wiki和知识库也可能变得难以管理，并可能需要额外的努力来保持最新。
会议和讨论：另一种记录架构决策的方法是定期举行会议或讨论来回顾和记录决策。这种方法对于重视面对面沟通和合作的团队可能很有用，但对于远程团队或时区不同的成员可能不那么有效。