Почетна Преглед Помоћ
Пријавите се
user5
/
forge_admin
1
0
Креирај огранак 0
Датотеке Дискусије 0 Захтеви за спајање 0 Вики
Грана: master
Гране Ознаке
forge_admin
/
code-copilot
/
changes
/
archive
/
2026-04-06-distributed-idempotent-gtis
/
spec.md

spec.md 5.3 KB
Пермалинк Историја Датотека

分布式幂等防重组件（美团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. 确认人：