关键词的观点是。幂等性 / 分布式锁 / Redisson / Token 机制 / SpEL 动态键 / 重复提交

一、问题场景：一个按钮点了两下数据库多了两条记录

从面试必考题来看，分布式程序如何保证接口幂等？

真实场景比面试题残酷得多：

• 使用者网卡，提交订单按钮点了 次 → 条相同的订单
• 支付回调由于网络抖动重试了 次 → 使用者被扣了 次钱
• MQ 使用者重启后重新消费 → 库存被扣成负数
• 前端没有防重复提交。loading 遮罩失效 → 审批单重复创建

这些问题的根因都一样：同一个业务操作被多次执行，但程序没有识别出"这是同一个操作"。怎么说呢，

Forge Admin 的 forge-starter-idempotent 模块给出的答案是：一个 @Idempotent 注解。三种策略，覆盖从"直接拒绝"到"返回缓存结果"再到"Token 防重"的全部场景。

二、方法：一个注解，三种策略

@Idempotent 注解

@Target
@Retention
public @interface Idempotent {
String prefix default "idempotent:";// 幂等键前缀
int expire default -1;// 键过期时间
String key default "";// SpEL 表达式
String message default "请勿重复提交";// 提示消息
IdempotentStrategy strategy default RETURN_CACHE;// 策略
int cacheExpire default -1;怎么说呢，// 结果缓存时间
boolean cacheResult default true;// 是否缓存结果
boolean deleteKeyAfterSuccess default false;// 成功后删键
}

至于策略一。严格模式——直接拒绝

从适用于来看，支付、转账等绝不允许重复的场景。

@Idempotent(
key = "'payment:' + #request.paymentId",strategy = IdempotentStrategy.STRICT,message = "支付请求正在处理中。请勿重复提交")
public PaymentResult pay {
// 支付逻辑
}

实现原理：

请求进入 → lockManager.tryLock
→ 获取锁成功 → 执领域务逻辑 → 释放锁 → 返回结果
→ 获取锁失败 → 说明有同名请求正在处理 → throw IdempotentException
使用 Redisson 分布式锁做互斥：同一时刻只有一个请求能获得锁并执领域务逻辑，后来的请求直接拒绝。

策略二这方面。缓存模式——返回上次结果

适用于这方面，查询类接口、不介意返回"旧"结果的场景。说起来，这是默认策略。

@Idempotent(
key = "'order:query:' + #orderId",strategy = IdempotentStrategy.RETURN_CACHE。cacheExpire = /* 缓存分钟 */)
public OrderDTO queryOrder {
return orderService.getById;}

# 实现原理：

请求进入 → lockManager.tryLock
→ 获取锁成功：
执领域务逻辑
将结果缓存到 Redis Hash
锁
返回结果
→ 获取锁失败：
等待100ms →
查 Redis 缓存：
有缓存结果 → 直接返回缓存
无缓存 → 抛异常
这个策略的精妙之处在于"并发请求的 '等一等' 逻辑":不是直接返回可能为空的缓存，而是给第一个请求留出执行时间。

策略三这方面。Token 模式——先领号再办事

适用于这方面，表单提交、审批操作等需要“先获取凭证”的场景。这是最安全也最复杂的一种。

@Idempotent(
key = "'leave:submit:' + #requestId",strategy = IdempotentStrategy.TOKEN_REQUIRED,deleteKeyAfterSuccess = true) // 一次性操作。
提交成功删除幂等键
public LeaveResult submitLeave {
// 请假申请逻辑
}

# 主要点：TOKEN 的“验证 + 消费”必须原子化——先标记为 CONSUMED，再执领域务。如果有人拿同一个 TOKEN 第二次请求。 校验时发现已经是 CONSUMED，直接拒绝。

三、数据结构：幂等键与缓存存储

Redis 存储结构

• 锁键 ： Key : idempotent:lock:{幂等键} Value : RLock
• 结果缓存 ： Key : idempotent:result:{幂等键} Fields : requestId : “请求唯一标识” result : “序列化业务结果” status : “SUCCESS/FAIL” executeTime : “时间戳” TTL : 默认3600s
• TOKEN 缓存 ： Key : idempotent:token:{token值} Value : UNUSED | CONSUMED TTL ：300s 未使用时 |60s 消费后

  幂等键生成规则

  SpEL 表达式实战示例表格​​​​​​
  # 单个参数:	'order:' + #orderId​​​​​​​	idempotent:order: ​​​​
  # 对象属性:	'payment:' + #request.paymentId​​​​	idempotent:payment:PAY001​​​​
  # 多参数组合:	'user:' + #userId + ':action:' + #type​​​​	idempotent:user::action:transfer​​​​
  # 常量全接口防重:	'global:submit'​​​​	idempotent:global:submit​​​​​
  注意事项 — SpEL解析错误导致共享空键信息！建议配合参数校验或兜底异常处理。​​​​​​​​​​​​​​ --- 四、实现链路：从注解到拒绝的每一步 切面入口 ： IdempotentAspect @Around || @within") public Object around throws Throwable { String idempKey = keyGenerator.generate,idemp.key);IdemStrategyHandler handler = strategyHandlerMap.get);其实，return handler.handle;} 切面只做两件事——生成幂等键与把控制权交给对应策略处理器。业务层完全由 StrategyHandler 内部实现；新增策略只需实现该接口，--- Redisson 分布式锁实现 public class RedissonLockManager implements LockManager{ private static final String LOCK_PREFIX ="idemptetlock:";private static final long DEFAULT_WAIT_TIME_SEC =5;private static final long DEFAULT_LEASE_TIME_SEC =30;@Override public boolean tryLock{ RLock lock=rClient.getLock;return lock.tryLock;} @Override public void unlock{ RLock lock=rClient.getLock;if) lock.unlock;} } ⚠️ 注意点 — {lease}硬编码为30秒，如果业务超时会导致两个实例同时执领域务。 --- Token 验证 & 消费原子化改进建议 当前实现这方面，java boolean validate{return redis.has;} boolean consume{redis.set;} 高并发下存在竞争窗口，可改为 Lua 原子脚本： lua local status = redis.call if status == 'UNUSED' n redis.call end return status --- 五、设计取舍：我们做了哪些选择？为什么，💡