JEECG-Boot接口幂等性实战：Token+分布式锁避坑

JEECG-Boot接口幂等性实战Token分布式锁避坑【免费下载链接】jeecg-boot【低代码v2.0一句话即可生成整个系统】企业级AI低代码平台一键生成前后端代码甚至整个系统。 AI Skills 一句话画流程、设计表单、生成报表、大屏。内置 AI应用平台涵盖AI聊天、知识库、流程编排、MCP插件等兼容主流大模型。引领AI低代码「Skills 生成 → 在线配置 → 代码生成 → 手工合并-AI修改」开发模式解决 Java 项目 90% 重复工作提高效率又不失灵活。项目地址: https://gitcode.com/GitHub_Trending/je/jeecg-boot用户连点两次「确认下单」网关超时又触发了一次重试数据库里凭空多出两条订单——这是接口幂等性失效最常见的翻车现场。JEECG-Boot 对这个问题有一套现成的答案Token 机制管前端防重复提交Redis 分布式锁管后端并发控制。本文带你把 JEECG-Boot 接口幂等性的原理讲透并走完两套方案的完整配置流程。为什么接口会重复提交先看三条真实的重复路径网络层连接超时后网关自动重试同一个请求被执行为两条用户层手快双击提交按钮或者浏览器「后退重发」消息层MQ 消费失败后重投同一条消息被处理多次。三条路径指向同一个后果——同一笔业务被执行了不止一次订单重复、库存扣两次、对账对不平。接口幂等性就是治这个病的而且它不是单点手段需要分层设防。两种防护思路一张表看懂 JEECG-Boot 里防重复提交主要靠两套机制一个在前端侧拦截一个在后端侧互斥对比维度前端拦截Token后端互斥分布式锁作用层级请求入口每次请求都要过一道校验业务逻辑执行期跨实例互斥典型场景用户双击提交、订单/表单保存秒杀扣库存、定时任务跨节点防重实现复杂度低框架已内置中需引入锁 starter是否依赖中间件依赖 Redis 缓存 Token依赖 Redis底层 Redisson一句话概括Token 是「门禁」回答你是谁、有没有资格进来分布式锁是「会议室锁」回答同一时间只允许一个人操作这间屋子。两者管的事不一样后面分别拆解。Token 机制 5 步走读JEECG-Boot 的 Token 本质是「JWT Redis 缓存」组合登录时签发之后每个请求都拿它过校验关卡。完整生命周期分 5 步获取用户登录成功服务端签发 JWT同时写入 Redis 并设置过期时间缓存Token 有效期由 Redis 的 TTL 维持请求持续到达时自动续期——只要你在用就不会中途掉线携带前端把 Token 放进请求头随每个请求一起发出验证网关过滤器统一调用TokenUtils.verifyToken依次检查 Token 是否存在、有没有被篡改、账号状态是否正常、是否过期销毁退出登录或修改密码时删除 Redis 中的 Token 缓存TTL 到期也会自然销毁。核心验证逻辑在 TokenUtils 里剥掉日志只剩骨架// 第一关Token 为空直接拒绝防止无凭证请求 if (StringUtils.isBlank(token)) { throw new JeecgBoot401Exception(token不能为空!); } // 第二关解密出用户名解不出说明 Token 被篡改 String username JwtUtil.getUsername(token); if (username null) { throw new JeecgBoot401Exception(token非法无效!); } // 第三关用户必须存在且账号状态正常防止已锁定账号 LoginUser user TokenUtils.getLoginUser(username, commonApi, redisUtil); if (user null || user.getStatus() ! 1) { throw new JeecgBoot401Exception(用户不存在或已锁定!); } // 第四关校验有效期并自动续期过期 Token 一律放行不了 if (!jwtTokenRefresh(token, username, user.getPassword(), redisUtil)) { throw new JeecgBoot401Exception(token已过期!); }这段代码在防什么一行关卡挡住四类请求——没带 Token 的、Token 被篡改的、账号已被锁的、Token 已过期的它就是重复提交的守门员。分布式锁防并发3 步配好就能用Token 只能挡「同一个用户重复来」挡不住「多个实例同时干同一件事」——跨实例并发必须交给分布式锁。JEECG-Boot 封装了锁 starter参考仓库里的 DemoLockTest 样例3 步就能跑起来① 引入依赖。版本在根 pom.xml 统一管理模块里声明即可!-- 引入 JEECG-Boot 官方分布式锁 starter底层 Redisson -- dependency groupIdorg.jeecgframework.boot3/groupId artifactIdjeecg-boot-starter-lock/artifactId version${jeecg-starter.version}/version /dependency这一行 starter 把 Redisson 客户端的初始化全封装了你不需要自己 new 客户端。② 配置 Redisson。锁 starter 完全基于 Redis没有额外中间件在 application.yml 里配好 Redis 连接就行# application.yml锁 starter 复用项目已有的 Redis spring: redis: host: 127.0.0.1 # Redis 地址 port: 6379 # Redis 端口需要微调 Redisson 自身参数看门狗续期、重试策略等时再放一份 redisson.yaml 到 resources 目录并在配置里指向它。③ 加锁注解式和编程式两种姿势// 注解式一行 JLock方法在所有实例间互斥 JLock(lockKey demo:lock:order) public void createOrder() { /* 业务逻辑 */ } // 编程式锁 key 动态拼接tryLock 时务必带上过期时间 if (redissonLock.tryLock(demo:lock: orderId, -1, 60)) { try { /* 业务逻辑 */ } finally { redissonLock.unlock(demo:lock: orderId); } }注解式适合固定锁 key 的场景加个注解零侵入编程式适合锁 key 随业务参数变化的场景代价是你要自己对释放负责。选型建议 常见坑JEECG-Boot 接口幂等性实现方案落地怎么选接口幂等性实现方案三句话如果你只是想挡住用户双击和表单重复提交就选 Token 机制JEECG-Boot 已内置零开发如果你是多实例部署、定时任务或扣库存这类跨节点场景就选分布式锁如果你是秒杀级高并发且业务链路复杂就选两者组合Token 拦在入口锁护住关键段。最常见的 3 个坑 ⚠️坑一忘记释放锁现象锁被永久占用后续所有请求全部等待失败原因业务中途抛异常代码没走到 unlock 那一行解法unlock 放 finally 里或者依赖锁的过期时间兜底。坑二锁没设超时现象持锁实例宕机后锁永远不消失整个功能卡死原因加锁时没传过期时间看门狗也没接管解法编程式加锁必须传 expireSeconds如tryLock(key, -1, 60)。坑三Token 缓存没设过期时间现象被盗的 Token 可以无限期重放请求原因签发时往 Redis 写缓存却没配 TTL解法写入时同步设置过期时间并复用jwtTokenRefresh的续期逻辑。Token 守门口分布式锁护关键段幂等性就是两者合力下的结果。建议先通读锁模块的 DemoLockTest 样例再把它落到你的业务接口上。【免费下载链接】jeecg-boot【低代码v2.0一句话即可生成整个系统】企业级AI低代码平台一键生成前后端代码甚至整个系统。 AI Skills 一句话画流程、设计表单、生成报表、大屏。内置 AI应用平台涵盖AI聊天、知识库、流程编排、MCP插件等兼容主流大模型。引领AI低代码「Skills 生成 → 在线配置 → 代码生成 → 手工合并-AI修改」开发模式解决 Java 项目 90% 重复工作提高效率又不失灵活。项目地址: https://gitcode.com/GitHub_Trending/je/jeecg-boot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考