有件软件工程师们特别讨厌的事，而这正是细节上的不同，区分出好与坏的软件工程师：他们又是如何编写项目文档的呢？

几年前，我负责启动了一个金融科技项目。由于我们决定迅速行动，可扩展性并不是优先考虑的事情。我们的重点是验证这个想法，于是我们快速推进，开发了APIs、架构和系统，采用了简单的解决方案，并未特别担心未来的扩展。

毕竟，作为负责后端和基础设施的我，虽然记性不错，但六个月后可能记不清所有细节了。

在我的研究中，我发现了一个我喜欢的惯例说法：ADR —— 即架构决策记录（ADR）。


这实际上是一个文档，记录了对架构进行的所有修改，包括修改本身、其影响以及我们从中获得的教训。

把它想象成个人日记中的团队版本。

• 人有时候会忘记： 记录变化对我们来说很重要，因为为什么选择这种架构而不是那种架构。

• 它让团队变得更好： 假设你已经为某个问题尝试了不同的解决方案，并记录了成功和失败。你可以从中学习，其他人也能学到，甚至后来加入的开发者。

• 未来的开发者会感谢你： 想象一下，一个开发者来到一个代码库，试图理解五年前的某个改变背后的原因。某个开发者可能正为此感到困扰，因为之前的工程师离开时没有留下记录，他们对此感到不满。而在另一家公司，一个开发者找到一份 ADR 解释了这些变更，顿时觉得感激不尽。

那你该怎么写呢？

有一些惯例需要遵循，但你可以根据最适合自己来调整它们。

让我受到启发的大会在这里：https://adr.github.io/madr/。这里也可以查看亚马逊的ADR过程：https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html。

这里有一个你可以用的模板。

# 示例标题：用户数据的数据库选择

## 背景和问题描述

随着我们用户基数的增长，我们需要一个可扩展的数据库来高效地存储和管理用户数据。

## 决策考虑因素

* 可扩展性
* 数据一致性
* 与现有服务的集成简便

## 考虑的选项

* PostgreSQL
* MongoDB
* Amazon DynamoDB

## 决策结果

选择：**PostgreSQL**，因为它提供了强大的数据一致性，并且与我们对复杂查询的需求相匹配。

### 后果

* **好：** 支持ACID特性，增强数据可靠性保障。
* **坏：** 可能需要更多时间来调整以实现大规模数据量的高性能。

### 确认

我们将定期进行负载测试和性能审查，以确保随着用户基数扩大时的性能。

## 各选项的优缺点

### PostgreSQL

* **好：** 支持ACID特性，强大的社区支持。
* **中立：** 设置和调整可能需要更多时间。
* **坏：** 缺乏原生的水平扩展支持。

### MongoDB

* **好：** 灵活的模式，支持水平扩展。
* **坏：** 不支持跨集合的ACID一致性，限制了数据完整性。

## 更多信息

更多详细信息，请参阅这里提供的数据库性能评估[此处](https://dev.to/link-to-evaluation)。

进入全屏，退出全屏

这种类型的文档可以存在于项目仓库、Notion 或 JIRA 中。

在我的上一家公司，当时是前端工程师，我们没有任何文档记录架构变更。

通过将每次更改与 GitLab 问题关联，我们使用问题分支来跟踪几个月后实施的更改背后的原由。

这种做法多次救了我们。我经常说，无论你或你的队友有多聪明——无论谁是你的CTO（首席技术官）、经理或者是任何参与项目的人员——他们不可能回忆起两年前做过的每一个技术决定。

当然，除非你和那些传说中的10x工程师一起工作。😆

这就是这篇文章的全部内容了。我们讨论了公司和科技团队领导如何在项目中使用ADR（架构决策记录）来记录架构决策，以及这对他们、团队成员甚至后来接手项目的人有多大帮助。

如果您有任何想分享的经验或对这篇文章的想法，欢迎在下面留言。

我一直乐于接受反馈，也高兴参与能够帮助我们一起学习与成长的交流。

如果你喜欢这篇文章，想获得更多这样的见解，订阅我的通讯吧，每周都会将贴士、教程和故事直接发送到你的邮箱里！