# 分布式幂等防重组件（美团GTIS方案实现）
> status: apply
> created: 2026-04-06
> complexity: 🔴复杂
## 1. 背景与目标
### 背景
当前系统缺乏统一的分布式幂等防重机制，存在以下问题：
1. 接口重复提交、网络重试、消息重复消费等场景容易导致数据重复插入、业务逻辑重复执行等问题
2. 各业务模块自行实现幂等逻辑，代码重复、实现不规范，存在漏判、误判风险
3. 缺乏统一的监控、统计、降级能力，出现幂等问题排查困难

### 目标
参考美团GTIS（Global Token Idempotent Service）方案，实现通用分布式幂等防重组件：
1. ✅ 低侵入：提供注解式使用方式，业务代码无需修改核心逻辑
2. ✅ 多场景支持：支持Web接口、RPC调用、消息消费等多种场景的幂等防护
3. ✅ 灵活配置：支持自定义幂等键生成策略、存储介质、过期时间、异常处理策略
4. ✅ 高可用：支持集群部署、降级开关、容错机制，不影响主业务流程
5. ✅ 可观测：提供幂等请求统计、命中日志、告警能力
## 2. 代码现状（Research Findings）
> 每个结论必须有代码出处（文件路径 + 类名/方法名）
### 2.1 相关入口与链路
待调研：
- 后端统一请求拦截器实现位置
- Spring Boot 自动配置扩展点
- Redis 操作现有封装
### 2.2 现有实现
待调研：
- 是否存在零散的幂等实现
- 现有框架的拦截器/切面扩展能力
### 2.3 发现与风险
待补充
## 3. 功能点
- [ ] 核心功能1：@Idempotent注解定义与AOP切面实现
- [ ] 核心功能2：幂等Token生成与校验服务（支持Header/参数/Body等多种Token传递方式）
- [ ] 核心功能3：多种幂等键生成策略（SpEL表达式、自定义策略接口）
- [ ] 核心功能4：Redis幂等存储实现（支持原子操作、过期时间、自动清理）
- [ ] 扩展功能5：支持多种幂等模式（防重提交、防重入、执行结果缓存）
- [ ] 扩展功能6：降级配置、告警统计、日志记录
## 4. 业务规则
待补充
## 5. 数据变更
| 操作 | 表名 | 字段/索引 | 说明 |
|------|------|-----------|------|
| 新增 | 无（Redis存储） | - | 幂等数据存储在Redis中，无需修改业务库 |
## 6. 接口变更
| 操作 | 接口 | 方法 | 变更内容 |
|------|------|------|----------|
| 新增 | - | - | 新增注解和切面，不影响现有接口 |
## 7. 影响范围
- 后端基础组件层：新增forge-starter-idempotent启动器
- 业务模块：可按需引入依赖，使用@Idempotent注解
## 8. 风险与关注点
> ⚠️ 涉及资金/状态流转/权限变更必须标注
- ⚠️ 风险1：Redis故障时的降级策略，需要保证不影响主业务流程
- ⚠️ 风险2：幂等键冲突问题，需要保证生成的幂等键全局唯一
- ⚠️ 风险3：性能影响，需要保证幂等校验的耗时在10ms以内
## 8.5 测试策略
- **测试范围**：单元测试覆盖核心逻辑、集成测试覆盖Web接口场景、性能测试验证高并发下的表现
- **覆盖率目标**：核心代码覆盖率100%
- **独立 Test Spec**：是
## 9. 待澄清
- [x] 问题1：是否需要支持除Redis之外的存储介质？→ 仅支持Redis
- [x] 问题2：幂等默认过期时间设置为多长比较合适？→ 10分钟（可自定义）
- [x] 问题3：是否需要支持接口级别的幂等配置全局开关？→ 需要
## 10. 技术决策
1. **存储方案**：仅使用Redis作为幂等存储介质，利用Redis原子操作保证高性能和一致性
2. **默认配置**：幂等记录默认过期时间10分钟，可通过@Idempotent注解的expire参数自定义
3. **开关控制**：支持全局配置开关（idempotent.enabled=true/false），注解优先级高于全局配置
4. **幂等键生成**：默认使用"用户ID+接口路径+参数哈希"作为幂等键，支持SpEL表达式自定义
5. **异常处理**：默认幂等校验失败抛出业务异常，可配置为返回上一次执行结果
6. **高可用保障**：Redis异常时自动降级，不影响主业务流程执行，同时输出告警日志
## 11. 执行日志
| Task | 状态 | 实际改动文件 | 备注 |
|------|------|-------------|------|
| Task1: 创建幂等组件模块结构与基础依赖 | ✅ 完成 | forge-starter-idempotent/pom.xml, forge-starter-parent/pom.xml, AutoConfiguration.imports | - |
| Task2: 定义@Idempotent注解与配置类 | ✅ 完成 | Idempotent.java, IdempotentProperties.java, IdempotentConstant.java | - |
| Task3: 实现幂等键生成器 | ✅ 完成 | SpelUtil.java, IdempotentKeyGenerator.java, DefaultIdempotentKeyGenerator.java | - |
| Task4: 实现Redis幂等存储服务 | ✅ 完成 | IdempotentException.java, IdempotentStorageService.java, RedisIdempotentStorageService.java | - |
| Task5: 实现AOP切面与Web拦截器 | ✅ 完成 | IdempotentAutoConfiguration.java, IdempotentAspect.java | - |
| Task6: 实现全局开关与异常处理 | ✅ 完成 | IdempotentException.java（修改继承BusinessException） | - |
| Fix: 修复代码审查发现的问题 | ✅ 完成 | 移除未使用的RedissonClient依赖、改进参数名获取、添加SpEL异常处理、添加切面全局开关检查 | - |
## 12. 审查结论
## 13. 确认记录（HARD-GATE）
- **确认时间**：
- **确认人**：