forge_admin/forge-docs/backend/modules/idempotent.md

分布式幂等（forge-starter-idempotent）

基于注解的分布式幂等框架，支持多种策略和 Redisson 分布式锁。

快速开始

1. 引入依赖

<dependency>
    <groupId>com.mdframe.forge</groupId>
    <artifactId>forge-starter-idempotent</artifactId>
</dependency>

2. 使用 @Idempotent 注解

@PostMapping("/order")
@Idempotent(prefix = "order:create", expire = 600, message = "订单创建中，请勿重复提交")
public RespInfo<Order> createOrder(@RequestBody OrderCreateRequest request) {
    // ...
}

核心功能

幂等策略

策略	说明	适用场景
STRICT	严格拒绝，重复请求直接抛出异常	支付、下单等严格幂等场景
RETURN_CACHE（默认）	重复请求返回缓存的上次执行结果	查询后写、耗时的计算
TOKEN_REQUIRED	必须先获取幂等 Token，携带 Token 才能执行	前端表单提交

注解属性

属性	类型	默认值	说明
prefix	String	"idempotent:"	Redis Key 前缀
expire	int	600	幂等 Key 过期时间（秒）
key	String	""	SpEL 表达式，用于自定义幂等 Key
message	String	"请勿重复提交"	重复提交时的提示信息
deleteKeyAfterSuccess	boolean	false	成功后是否删除幂等 Key
strategy	IdempotentStrategy	RETURN_CACHE	幂等策略
cacheExpire	int	3600	缓存结果过期时间（秒）
cacheResult	boolean	true	是否缓存执行结果
enableMetrics	boolean	true	是否启用 Prometheus 指标

TOKEN_REQUIRED 策略 — Token API

使用 TOKEN_REQUIRED 策略时，需要先获取幂等 Token：

POST /api/idempotent/token/generate
{
  "prefix": "order:create",
  "expire": 300
}

# 返回
{
  "token": "a1b2c3d4-..."
}

执行请求时在请求头中携带 Token：

POST /api/order
X-Idempotent-Token: a1b2c3d4-...
Content-Type: application/json

{...}

SpEL 表达式自定义 Key

@Idempotent(prefix = "user:update", key = "#userId", expire = 300)
public RespInfo updateUser(@PathVariable Long userId, @RequestBody UserUpdateRequest request) {
    // 幂等 Key = "user:update:" + userId
}

配置项

forge:
  idempotent:
    enabled: true
    prefix: "idempotent:"
    expire: 600
    message: "请勿重复提交"
    cache:
      enabled: true
      expire: 3600
      maxSize: 10000
    lock:
      enabled: true
      waitTime: 3000   # 分布式锁等待时间（ms）
      leaseTime: 5000  # 分布式锁持有时间（ms）
    token:
      enabled: true
      expire: 300      # Token 过期时间（秒）
      header: "X-Idempotent-Token"

核心组件

组件	说明
IdempotentAspect	AOP 切面，拦截 @Idempotent 注解的方法
IdempotentKeyGenerator	幂等 Key 生成器，支持 SpEL 表达式
RedisTokenService	Redis Token 服务，管理 Token 生命周期
RedisResultCacheService	结果缓存服务，缓存执行结果
RedissonLockManager	Redisson 分布式锁管理器（带 Watchdog）
StrictStrategyHandler	STRICT 策略处理器
ReturnCacheStrategyHandler	RETURN_CACHE 策略处理器
TokenRequiredStrategyHandler	TOKEN_REQUIRED 策略处理器

执行流程

请求进入 → 生成/解析幂等 Key → 选择策略
  → STRICT: 尝试获取锁 → 失败则抛异常
  → RETURN_CACHE: 查缓存 → 有则返回，无则执行并缓存
  → TOKEN_REQUIRED: 验证 Token → 通过后走 RETURN_CACHE 流程