forge_admin/code-copilot/changes/archive/2026-04-06-distributed-idempotent-gtis/spec.md

分布式幂等防重组件（美团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 相关入口与链路

   待调研：

6. 后端统一请求拦截器实现位置

7. Spring Boot 自动配置扩展点

8. Redis 操作现有封装

   2.2 现有实现

   待调研：

9. 是否存在零散的幂等实现

10. 现有框架的拦截器/切面扩展能力

    2.3 发现与风险

    待补充

    3. 功能点

11. [ ] 核心功能1：@Idempotent注解定义与AOP切面实现

12. [ ] 核心功能2：幂等Token生成与校验服务（支持Header/参数/Body等多种Token传递方式）

13. [ ] 核心功能3：多种幂等键生成策略（SpEL表达式、自定义策略接口）

14. [ ] 核心功能4：Redis幂等存储实现（支持原子操作、过期时间、自动清理）

15. [ ] 扩展功能5：支持多种幂等模式（防重提交、防重入、执行结果缓存）

16. [ ] 扩展功能6：降级配置、告警统计、日志记录

    4. 业务规则

    待补充

    5. 数据变更

    操作	表名	字段/索引	说明
    新增	无（Redis存储）	-	幂等数据存储在Redis中，无需修改业务库

    6. 接口变更

    操作	接口	方法	变更内容
    新增	-	-	新增注解和切面，不影响现有接口

    7. 影响范围

17. 后端基础组件层：新增forge-starter-idempotent启动器

18. 业务模块：可按需引入依赖，使用@Idempotent注解

    8. 风险与关注点

    ⚠️ 涉及资金/状态流转/权限变更必须标注

19. ⚠️ 风险1：Redis故障时的降级策略，需要保证不影响主业务流程

20. ⚠️ 风险2：幂等键冲突问题，需要保证生成的幂等键全局唯一

21. ⚠️ 风险3：性能影响，需要保证幂等校验的耗时在10ms以内

    8.5 测试策略

22. 测试范围：单元测试覆盖核心逻辑、集成测试覆盖Web接口场景、性能测试验证高并发下的表现

23. 覆盖率目标：核心代码覆盖率100%

24. 独立 Test Spec：是

    9. 待澄清

25. [x] 问题1：是否需要支持除Redis之外的存储介质？→ 仅支持Redis

26. [x] 问题2：幂等默认过期时间设置为多长比较合适？→ 10分钟（可自定义）

27. [x] 问题3：是否需要支持接口级别的幂等配置全局开关？→ 需要

    10. 技术决策

28. 存储方案：仅使用Redis作为幂等存储介质，利用Redis原子操作保证高性能和一致性

29. 默认配置：幂等记录默认过期时间10分钟，可通过@Idempotent注解的expire参数自定义

30. 开关控制：支持全局配置开关（idempotent.enabled=true/false），注解优先级高于全局配置

31. 幂等键生成：默认使用"用户ID+接口路径+参数哈希"作为幂等键，支持SpEL表达式自定义

32. 异常处理：默认幂等校验失败抛出业务异常，可配置为返回上一次执行结果

33. 高可用保障：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）

34. 确认时间：

35. 确认人：