---

name: architecture-decision-records description: "用于创建、维护和管理架构决策记录（ADR）的全面模式，捕获重大技术决策背后的上下文和理由。" risk: unknown source: community date_added: "2026-02-27"

架构决策记录

用于创建、维护和管理架构决策记录（ADR）的全面模式，捕获重大技术决策背后的上下文和理由。

适用场景

• 做出重大架构决策
• 记录技术选型
• 记录设计权衡
• 新团队成员入职
• 审查历史决策
• 建立决策流程

不适用场景

• 只需要记录小的实现细节
• 变更是小补丁或常规维护
• 没有需要捕获的架构决策

操作指南

1. 捕获决策上下文、约束和驱动因素。
2. 记录考虑的选项及其权衡。
3. 记录决策、理由和后果。
4. 链接相关ADR并随时间更新状态。

核心概念

1. 什么是ADR？

架构决策记录捕获：

• 上下文：为什么我们需要做出决策
• 决策：我们决定了什么
• 后果：结果会怎样

2. 何时编写ADR

| 编写ADR | 跳过ADR | |-----------|----------| | 新框架采用 | 小版本升级 | | 数据库技术选型 | Bug修复 | | API设计模式 | 实现细节 | | 安全架构 | 常规维护 | | 集成模式 | 配置变更 |

3. ADR生命周期

提议 → 接受 → 废弃 → 被取代
              ↓
           拒绝

模板

模板1：标准ADR（MADR格式）

# ADR-0001: 使用 PostgreSQL 作为主数据库

## 状态

已接受

## 上下文

我们需要为新的电商平台选择主数据库。系统将处理：
- ~10,000 并发用户
- 具有层级分类的复杂产品目录
- 订单和支付的事务处理
- 产品全文搜索
- 门店定位的地理空间查询

团队有 MySQL、PostgreSQL 和 MongoDB 的经验。我们需要ACID合规性来处理金融事务。

## 决策驱动因素

* **必须具备ACID合规性** 用于支付处理
* **必须支持复杂查询** 用于报表
* **应支持全文搜索** 以减少基础设施复杂性
* **应有良好的JSON支持** 用于灵活的产品属性
* **团队熟悉度** 减少入职时间

## 考虑的选项

### 选项1：PostgreSQL
- **优点**：ACID合规，优秀的JSON支持（JSONB），内置全文搜索，PostGIS用于地理空间，团队有经验
- **缺点**：复制设置比MySQL稍复杂

### 选项2：MySQL
- **优点**：团队非常熟悉，简单复制，大社区
- **缺点**：JSON支持较弱，无内置全文搜索（需要Elasticsearch），无扩展则无地理空间支持

### 选项3：MongoDB
- **优点**：灵活模式，原生JSON，水平扩展
- **缺点**：多文档事务无ACID（决策时），团队经验有限，需要模式设计纪律

## 决策

我们将使用 **PostgreSQL 15** 作为主数据库。

## 理由

PostgreSQL 提供了最佳平衡：
1. **ACID合规性** 对电商事务至关重要
2. **内置能力**（全文搜索、JSONB、PostGIS）减少基础设施复杂性
3. **团队熟悉度** 减少学习曲线
4. **成熟生态系统** 拥有优秀的工具和社区支持

复制方面的轻微复杂性被减少额外服务（无需单独的Elasticsearch）所抵消。

## 后果

### 积极
- 单一数据库处理事务、搜索和地理空间查询
- 降低运维复杂性（更少的服务需要管理）
- 金融数据的强一致性保证
- 团队可以利用现有SQL专业知识

### 消极
- 需要学习PostgreSQL特定功能（JSONB、全文搜索语法）
- 垂直扩展限制可能需要更早引入只读副本
- 部分团队成员需要PostgreSQL特定培训

### 风险
- 全文搜索可能不如专用搜索引擎扩展性好
- 缓解：设计时考虑在需要时添加Elasticsearch的可能性

## 实施说明

- 使用JSONB存储灵活的产品属性
- 使用PgBouncer实现连接池
- 设置流复制用于只读副本
- 使用pg_trgm扩展进行模糊搜索

## 相关决策

- ADR-0002：缓存策略（Redis）- 补充数据库选择
- ADR-0005：搜索架构 - 如果需要Elasticsearch可能取代本决策