# ADR-002: 响应式编程选型

> 文档编号: GYM-ADR-002  
> 版本: v1.0  
> 日期: 2026-03-04  
> 作者: 张翔  
> 状态: 已采纳

---

## 状态

已采纳

---

## 决策时间

2026-03-04

---

## 决策背景

健身房管理系统需要支持高并发场景（预约高峰期、签到高峰期），传统阻塞式编程模型无法满足性能需求。

---

## 决策内容

采用 Spring WebFlux + R2DBC 响应式编程模型，而非传统的 Spring MVC + JPA。

---

## 决策理由

### 1. 性能优势明显

| 性能指标 | Spring MVC + JPA | WebFlux + R2DBC | 提升幅度 |
|---------|-----------------|-----------------|---------|
| 并发连接数 | 200-500 | 2000-5000 | **10x** |
| API响应时间(P99) | 500-800ms | 200-400ms | **50%↓** |
| 吞吐量(QPS) | 500-1000 | 3000-5000 | **5x** |
| 内存占用 | 2-4GB | 512MB-1GB | **75%↓** |
| CPU利用率 | 60-80% | 40-60% | **25%↓** |
| 线程数 | 200-500 | 10-20 | **95%↓** |

### 2. 资源利用率高
- 非阻塞I/O模型
- 少量线程处理大量请求
- 内存占用低

### 3. 适合高并发场景
- 预约高峰期（每天18:00-20:00）
- 签到高峰期（每天9:00-10:00、18:00-19:00）
- 支付流程（实时性要求高）

### 4. 统一技术栈
- 全栈响应式编程
- 从Web层到数据访问层统一模型
- 代码风格一致

---

## 替代方案

### Spring MVC + JPA（传统阻塞式）

**优势**：
- 团队熟悉度高
- 生态成熟
- 调试简单
- 学习成本低

**劣势**：
- 并发能力有限
- 资源占用高
- 线程阻塞模型

**不选择原因**：
- 无法满足高并发需求
- 资源利用率低
- 性能瓶颈明显

---

## 影响范围

- 技术栈选型
- 代码编写方式
- 测试方法
- 调试技巧
- 团队培训

---

## 后果

### 正面影响
- ✅ 并发能力提升10倍
- ✅ 响应时间降低50%
- ✅ 资源利用率提升75%
- ✅ 服务器成本降低60%

### 负面影响
- ⚠️ 学习曲线陡峭（需要4-6周培训）
- ⚠️ 调试难度增加
- ⚠️ 生态相对不成熟
- ⚠️ 代码可读性降低

---

## 前提条件

### 1. 团队培训
- 响应式编程基础（1周）
- WebFlux实战（2周）
- R2DBC实战（1周）
- 性能调优（1周）

### 2. 代码审查
- 100%代码审查覆盖
- 响应式编程规范检查
- 性能测试验证

### 3. 监控体系
- 响应式指标监控
- 背压机制监控
- 错误处理监控

---

## 风险缓解

### 风险1：团队学习曲线
- **缓解措施**：安排4-6周培训，建立代码审查机制
- **应急方案**：关键模块由资深工程师负责

### 风险2：调试困难
- **缓解措施**：建立完善的日志体系，使用响应式调试工具
- **应急方案**：关键路径增加日志输出

### 风险3：生态不成熟
- **缓解措施**：选择成熟的响应式库，避免使用实验性功能
- **应急方案**：关键功能准备阻塞式降级方案

---

## 相关文档

- [T-ILD-基础版-技术实现详细设计](../技术架构/T-ILD-基础版-技术实现详细设计.md)
- [EVAL-002-性能与可扩展性评估报告](../../03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md)

---

## 参考资料

- Spring WebFlux官方文档
- R2DBC规范文档
- Reactor核心库文档
- 响应式编程实战