ForgeAdmin实战：开源项目分布式幂等组件 v2.0 升级

我在开源项目重构了分布式幂等组件支持三种策略、Token防重放、结果缓存为什么要重构幂等组件在企业级开发中幂等性是保障数据一致性必不可少的能力。之前我在 Forge Admin 开源项目中实现了一个基础版本的幂等组件但随着使用场景越来越多发现了一些问题问题影响无结果缓存重复请求只能拒绝用户体验差缺少Token机制无法防范CSRF和恶意重放攻击没有监控统计无法评估幂等效果和性能锁实现简单仅使用SETNX长时间业务可能锁过期策略单一只支持拒绝无法满足不同场景需求因此我参考了业内主流开源项目的设计思想对幂等组件进行了全面重构推出了 v2.0 版本。重构后的整体架构重构后的架构更加清晰分层职责明确┌─────────────────────────────────────────────────────────┐ │ Idempotent Framework v2.0 │ ├─────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Idempotent │ │ Idempotent │ │ Context │ │ │ │ Annotation │ │ Aspect │ │ Manager │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Token │ │ Result │ │ Lock │ │ │ │ Service │ │ Cache │ │ Manager │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Monitor │ │ Storage │ │ Strategy │ │ │ │ Metrics │ │ (Redis) │ │ Provider │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └─────────────────────────────────────────────────────────┘核心特性1. 支持三种幂等策略针对不同业务场景提供三种不同的幂等处理策略策略处理逻辑适用场景STRICT严格拒绝重复请求订单创建、支付处理等关键操作RETURN_CACHE返回上次缓存结果查询类操作、可重复读取TOKEN_REQUIREDToken验证优先前端防重复提交、防重放攻击2. 幂等结果缓存当重复请求发生时可以返回上次成功执行的缓存结果无需重复执行业务逻辑提升用户体验用户无需重新提交减少系统负载避免重复计算缓存有效期可配置3. Token机制防重放提供完整的Token生成、验证、消费机制Token单次消费使用后即失效Token绑定用户ID防止跨用户盗用短TTL减少泄露风险提供REST API供前端调用4. Redisson分布式锁基于Redisson实现增强型分布式锁支持看门狗自动续期长时间业务执行不会提前过期可配置锁等待时间和租约时间公平锁支持避免饥饿5. Prometheus监控集成内置完整的监控指标指标类型说明idempotent.requests.totalCounter请求总数idempotent.requests.successCounter成功次数idempotent.requests.duplicateCounter重复次数idempotent.cache.returnedCounter缓存返回次数idempotent.cache.hit.rateGauge缓存命中率idempotent.execution.timeTimer执行耗时分布快速开始1. 添加依赖dependency groupIdcom.mdframe.forge/groupId artifactIdforge-starter-idempotent/artifactId /dependency2. 配置文件forge: idempotent: enabled: true prefix: idempotent: expire: 600 message: 请勿重复提交 cache: enabled: true expire: 3600 token: enabled: true expire: 300 header: X-Idempotent-Token lock: enabled: true wait-time: 3000 lease-time: 5000使用示例示例1严格模式订单创建PostMapping(/order/create) Idempotent( strategy IdempotentStrategy.STRICT, prefix order:, key #orderRequest.orderId, message 订单正在处理中请勿重复提交 ) public RespInfoOrder createOrder(RequestBody OrderRequest orderRequest) { return RespInfo.success(orderService.create(orderRequest)); }行为第一次请求正常执行重复请求直接抛出异常拒绝。示例2缓存模式订单查询GetMapping(/order/{orderId}) Idempotent( strategy IdempotentStrategy.RETURN_CACHE, prefix order:query:, key #orderId, cacheExpire 300 ) public RespInfoOrder queryOrder(PathVariable String orderId) { return RespInfo.success(orderService.getById(orderId)); }行为第一次请求执行查询并缓存结果重复请求直接返回缓存结果不访问数据库。示例3Token模式支付处理第一步前端获取Tokenconst res await axios.post(/api/idempotent/token/generate, { prefix: payment }); const token res.data.data.token;第二步携带Token请求await axios.post(/api/payment/process, paymentData, { headers: { X-Idempotent-Token: token } });第三步后端验证PostMapping(/payment/process) Idempotent( strategy IdempotentStrategy.TOKEN_REQUIRED, prefix payment:, key #paymentRequest.paymentId ) public RespInfoPaymentResult processPayment(RequestBody PaymentRequest request) { return RespInfo.success(paymentService.process(request)); }Token API 一览获取TokenPOST /api/idempotent/token/generate { prefix: order // 可选 } → { code: 200, data: { token: abc123..., expireSeconds: 300, createTime: 1678923456789 } }批量获取TokenPOST /api/idempotent/token/batch-generate { count: 10, prefix: order }验证TokenPOST /api/idempotent/token/validate { token: abc123... } → { code: 200, data: true }Redis 存储结构Key类型Key格式TTL幂等标记idempotent:{prefix}:{businessKey}expire秒结果缓存idempotent:cache:{prefix}:{businessKey}cacheExpire秒Token存储idempotent:token:{prefix}:{tokenValue}tokenExpire秒分布式锁idempotent:lock:{prefix}:{businessKey}Redisson管理设计思路总结为什么选择这三种策略在实际业务中不同场景对幂等的需求是不一样的关键写操作如创建订单必须严格防止重复所以用STRICT模式读多写少的查询重复查询结果一样用RETURN_CACHE可以提升性能前端表单提交用户可能重复点击用TOKEN_REQUIRED配合Token可以有效防止重复提交为什么选择Redisson而不是自己实现Redisson的分布式锁已经经过生产环境验证特别是看门狗自动续期这个特性自己实现很容易出问题站在巨人肩膀上更好。结果缓存会不会有一致性问题是的如果业务数据更新了缓存还没过期会返回旧数据。所以建议缓存过期时间设置合理一般几分钟更新数据时可以提供手动清理缓存的接口不建议对一致性要求非常高的场景使用缓存模式踩坑记录坑1SpEL表达式解析没有异常处理一开始直接解析不捕获异常如果用户写错了表达式整个接口直接500。现在改成解析失败回退到参数哈希方案保证接口可用。坑2参数名获取方式兼容性问题一开始用StandardReflectionParameterNameDiscoverer如果编译没有开-parameters参数就获取不到参数名SpEL中的#参数名就失效了。现在改成DefaultParameterNameDiscoverer它会自动尝试多种方式兼容性更好。坑3全局开关动态不生效一开始只在自动配置上加了ConditionalOnProperty如果运行时通过配置中心关闭切面还是会执行。现在在切面切入点再次检查配置开关保证即时生效。项目地址完整代码已经开源在 Forge Admin https://gitee.com/ForgeLab/forge-admin欢迎 Star 关注如果你对幂等组件有更好的想法欢迎提 Issue 交流。总结这次重构让幂等组件从能用变成好用主要提升✅功能更完整三种策略、Token防重放、结果缓存✅可靠性更高Redisson分布式锁 看门狗续期✅可观测性Prometheus监控一切指标可查✅体验更好重复请求返回缓存用户无需等待如果你也在找一个开箱即用的分布式幂等解决方案不妨试试这个组件。#Java #SpringBoot #分布式 #幂等 #开源 #ForgeAdmin #架构重构