Spring Boot 接口幂等实战:用 Token + Redis 防重复提交

Spring Boot 接口幂等实战:用 Token Redis 防重复提交用户手抖双击了「提交订单」,或者网络卡了页面转圈他又点一次,结果后台生成了两条一模一样的订单。这是几乎每个交易类接口都要面对的问题:同一个业务操作被重复执行。前端加个 loading 禁用按钮只能挡君子,挡不住重发请求、挡不住网络重试、更挡不住恶意刷单。真正靠谱的做法是让接口本身幂等——同一个请求打多少次,结果都只生效一次。这篇用最常见的「Token Redis」方案手把手实现一遍。先看朴素做法为什么不够第一反应可能是「查一下数据库有没有相同订单」:// ❌ 查重再插入,并发下依然会重复if(orderMapper.findByBizId(bizId)null){orderMapper.insert(order);}问题在于「查」和「插」是两步,不是原子的。两个并发请求可能同时查到「没有」,然后同时插入,查重形同虚设。加数据库唯一索引能兜底,但那是最后一道防线,还会给库带来大量重复写压力。我们要在更前面把重复请求挡掉。方案思路:一次性 Token核心是「令牌只能用一次」:用户进入表单页时,先向后端申请一个唯一 Token,后端把它存进 Redis 并返回给前端。提交表单时,前端把 Token 放在请求头里带上。后端校验:Token 存在就原子地删除它并放行;不存在(已被删)就是重复提交,拒绝。关键就在第 3 步的「校验并删除」必须是原子操作,否则并发下又会出现两个请求都查到 Token 还在、都通过的情况。第一步:提供获取 Token 的接口RestControllerRequestMapping(/api/idempotent)publicclassTokenController{ResourceprivateStringRedisTemplateredis;privatestaticfinalStringPREFIXidem:token:;GetMapping(/token)publicMapString,StringgetToken(){StringtokenUUID.randomUUID().toString();// 存 Redis 并设过期,防止申请了不用堆积垃圾 keyredis.opsForValue().set(PREFIXtoken,1,5,TimeUnit.MINUTES);returnMap.of(token,token);}}Token 一定要设过期时间,用户申请了不提交是常态,不能让它永久占内存。第二步:用 Lua 脚本保证「校验删除」原子先看错误写法,分两步会有并发漏洞:// ❌ get 和 delete 之间有窗口,两个请求可能都 get 到 1if(redis.opsForValue().get(key)!null){redis.delete(key);// 放行……但可能已经有另一个请求也走到这}正确做法是用 Lua 脚本把「判断存在 删除」放在 Redis 里一次执行,Redis 单线程执行脚本天然原子:ComponentpublicclassIdempotentChecker{ResourceprivateStringRedisTemplateredis;// KEYS[1] 存在则删除并返回 1,不存在返回 0privatestaticfinalStringLUAif redis.call(get, KEYS[1]) then return redis.call(del, KEYS[1]) else return 0 end;privatefinalDefaultRedisScriptLongscriptnewDefaultRedisScript(LUA,Long.class);/** 返回 true 表示这是首次、放行;false 表示重复提交 */publicbooleancheck(Stringtoken){Longrredis.execute(script,Collections.singletonList(idem:token:token));returnr!nullr0;}}第三步:用注解 拦截器优雅接入不想每个接口都手写校验,可以做个注解,靠 AOP 统一拦:Target(ElementType.METHOD)Retention(RetentionPolicy.RUNTIME)publicinterfaceIdempotent{}AspectComponentpublicclassIdempotentAspect{ResourceprivateIdempotentCheckerchecker;Around(annotation(idempotent))publicObjectaround(ProceedingJoinPointpjp,Idempotentidempotent)throwsThrowable{HttpServletRequestreq((ServletRequestAttributes)RequestContextHolder.currentRequestAttributes()).getRequest();Stringtokenreq.getHeader(Idempotent-Token);if(tokennull||!checker.check(token)){// Token 缺失或已被用过,判定为重复提交thrownewIllegalStateException(请勿重复提交);}returnpjp.proceed();}}业务接口只需一个注解:PostMapping(/order)Idempotent// 加上它,重复提交自动被挡publicOrdercreateOrder(RequestBodyOrderReqreq){returnorderService.create(req);}几个容易忽略的坑Token 校验要放在业务执行之前。如果先执行业务再删 Token,业务耗时期间的重复请求还是会漏进来。过期时间要覆盖真实操作时长。用户填表可能填很久,5 分钟太短会误伤,按业务合理设置。Token 方案挡的是「重复提交」,不是「重复请求同一资源」。对于「同一笔支付回调可能被支付方重推多次」这种,业务方没法帮你申请 Token,应该用业务唯一键(如支付流水号)做幂等,思路一样:拿业务键去 RedissetIfAbsent,成功才处理。数据库唯一索引仍要保留。Redis 挂了、key 被误删都可能让防线失效,唯一索引是最后的兜底。小结Token Redis 幂等方案的要点:进页面先申请一次性Token 存 Redis,提交时带回来。校验用Lua 脚本原子地「判断删除」,别用 get 完再 delete,那有并发窗口。用注解 AOP统一接入,业务代码零侵入。Redis 是第一道防线,数据库唯一索引是最后兜底,两者都要有。一句话记忆点:幂等的本质是「让重复请求识别得出、且只有一个能通过」,而识别通过这一步必须原子——Lua 脚本就是干这个的。