以下代码均基于 Redisson 原生 API底层全部通过 Lua 脚本保证原子性可直接接入 Spring Boot 生产项目。一、分布式限流实现提供两种生产最常用的限流方案分别对应QPS 速率控制和并发数控制两类场景。1. 令牌桶限流RRateLimiter接口 QPS 限流首选基于令牌桶算法实现原子化完成令牌生成与消耗支持平滑限流、应对突发流量是接口级限流的最优方案。适用场景接口 QPS 限制、用户级调用频次控制、第三方接口调用限流。工程化封装注解 AOP第一步自定义限流注解Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface ApiRateLimiter { // 限流业务key String key(); // 限流模式OVERALL全局总限流PER_CLIENT每个客户端独立限流 RateType mode() default RateType.OVERALL; // 单位时间内生成的令牌总数 long rate() default 10; // 时间单位 RateIntervalUnit timeUnit() default RateIntervalUnit.SECONDS; // 单次请求消耗令牌数 int permits() default 1; // 限流提示语 String msg() default 系统繁忙请稍后重试; }第二步AOP 切面实现Aspect Component public class RateLimiterAspect { Resource private RedissonClient redissonClient; Around(annotation(limiter)) public Object around(ProceedingJoinPoint joinPoint, ApiRateLimiter limiter) throws Throwable { // 组装限流key按用户限流可自行拼接userId String limitKey limit: limiter.key(); RRateLimiter rateLimiter redissonClient.getRateLimiter(limitKey); // 幂等初始化限流器重复调用不覆盖配置 rateLimiter.trySetRate(limiter.mode(), limiter.rate(), 1, limiter.timeUnit()); // 原子获取令牌成功则执行业务 boolean allow rateLimiter.tryAcquire(limiter.permits()); if (!allow) { throw new BusinessException(limiter.msg()); } return joinPoint.proceed(); } }业务使用示例// 示例1全局接口限流每秒最多20次下单请求 ApiRateLimiter(key order:create, rate 20, msg 下单人数过多请稍后重试) public String createOrder(OrderDTO dto) { // 下单业务逻辑 return ORD System.currentTimeMillis(); } // 示例2按用户限流每个用户每分钟最多调用5次查询接口 // 注按用户限流需将userId拼入key可在AOP中从上下文获取userId动态拼接 ApiRateLimiter(key user:query:order, rate 5, timeUnit RateIntervalUnit.MINUTES) public ListOrderVO queryOrderList(Long userId) { // 查询业务逻辑 return Collections.emptyList(); }关键说明RateType.OVERALL集群所有节点共享总速率适合全局接口限流。按用户 / 租户限流将用户 ID 拼入限流 key每个用户对应独立限流器实现隔离。令牌桶容量默认等于速率值支持突发流量一次性消耗存量令牌。2. 并发数限流RSemaphore 信号量基于分布式信号量控制同时持有许可的线程总数即同一时间最多有多少个线程执行指定业务。适用场景限制并发执行的任务数如导出、批量处理、保护下游资源数据库、第三方接口。工具类封装Component public class ConcurrentLimitUtil { Resource private RedissonClient redissonClient; /** * 尝试获取并发许可 * param resourceKey 资源标识 * param maxConcurrent 最大并发数 * return true获取成功false并发已满 */ public boolean tryAcquire(String resourceKey, int maxConcurrent) { RSemaphore semaphore redissonClient.getSemaphore(concurrent: resourceKey); semaphore.trySetPermits(maxConcurrent); return semaphore.tryAcquire(); } /** * 释放并发许可必须在finally中调用 */ public void release(String resourceKey) { redissonClient.getSemaphore(concurrent: resourceKey).release(); } }业务使用示例public void exportOrderData() { String resourceKey export:order; // 限制同时最多3个导出任务 if (!concurrentLimitUtil.tryAcquire(resourceKey, 3)) { throw new BusinessException(当前导出任务过多请稍后再试); } try { // 执行导出业务 doExportExcel(); } finally { // 必须释放许可防止泄露 concurrentLimitUtil.release(resourceKey); } }二、分布式幂等实现提供两种主流幂等方案分别对应前端表单防重和后端业务防重两类场景。1. 令牌式幂等表单 / 接口防重复提交前端进入页面前申请唯一令牌提交时携带令牌服务端原子校验并删除令牌校验通过才执行业务。适用场景表单重复提交、按钮重复点击、前端接口防重。工具类封装Component public class IdempotentTokenService { Resource private RedissonClient redissonClient; private static final String TOKEN_PREFIX idempotent:token:; private static final long TOKEN_EXPIRE_MINUTES 5; /** * 生成幂等令牌 * param bizId 业务标识如用户ID隔离不同主体 * return 令牌字符串 */ public String generateToken(String bizId) { String token UUID.randomUUID().toString().replace(-, ); RBucketString bucket redissonClient.getBucket(TOKEN_PREFIX bizId); bucket.set(token, TOKEN_EXPIRE_MINUTES, TimeUnit.MINUTES); return token; } /** * 原子校验并删除令牌 * return true校验通过false令牌无效/已使用 */ public boolean checkAndRemove(String bizId, String token) { String key TOKEN_PREFIX bizId; Long result redissonClient.getScript().eval( RScript.Mode.READ_WRITE, if redis.call(GET, KEYS[1]) ARGV[1] then return redis.call(DEL, KEYS[1]) else return 0 end, RScript.ReturnType.INTEGER, Collections.singletonList(key), token ); return result ! null result 1; } }业务使用流程// 1. 前端进入页面时获取令牌 GetMapping(/token/get) public ResultString getToken(RequestParam Long userId) { return Result.success(idempotentTokenService.generateToken(userId.toString())); } // 2. 提交接口校验令牌 PostMapping(/order/submit) public ResultString submitOrder( RequestHeader(idempotent-token) String token, RequestBody OrderDTO dto ) { boolean valid idempotentTokenService.checkAndRemove(dto.getUserId().toString(), token); if (!valid) { return Result.fail(请勿重复提交); } // 执行业务 String orderNo orderService.createOrder(dto); return Result.success(orderNo); }2. 业务唯一键幂等后端回调 / 消息防重以业务唯一标识作为幂等键原子加锁并保留有效期有效期内相同业务号直接拒绝重复处理。适用场景支付回调、MQ 消息重复消费、接口重试防重、重复下单控制。工具类封装Component public class BizIdempotentService { Resource private RedissonClient redissonClient; private static final String KEY_PREFIX idempotent:biz:; private static final long DEFAULT_EXPIRE_MINUTES 30; /** * 尝试获取幂等锁 * param bizType 业务类型如PAY_CALLBACK、ORDER_CREATE * param bizNo 业务唯一单号 * param expireMinutes 幂等有效期 * return true首次请求false重复请求 */ public boolean tryIdempotent(String bizType, String bizNo, long expireMinutes) { String lockKey KEY_PREFIX bizType : bizNo; RLock lock redissonClient.getLock(lockKey); try { // 等待时间为0立即返回结果持有时间为幂等有效期 return lock.tryLock(0, expireMinutes, TimeUnit.MINUTES); } catch (InterruptedException e) { Thread.currentThread().interrupt(); return false; } } public boolean tryIdempotent(String bizType, String bizNo) { return tryIdempotent(bizType, bizNo, DEFAULT_EXPIRE_MINUTES); } /** * 手动释放幂等锁业务处理失败时调用允许后续重试 */ public void releaseIdempotent(String bizType, String bizNo) { RLock lock redissonClient.getLock(KEY_PREFIX bizType : bizNo); if (lock.isHeldByCurrentThread()) { lock.unlock(); } } }业务使用示例支付回调public void handlePayCallback(PayCallbackDTO callback) { // 支付流水号作为唯一键幂等有效期30分钟 boolean isFirst bizIdempotentService.tryIdempotent(PAY_CALLBACK, callback.getPayNo(), 30); if (!isFirst) { log.info(重复支付回调直接忽略流水号{}, callback.getPayNo()); return; } try { // 执行业务更新订单状态、记账、发货等 updateOrderPayStatus(callback.getOrderNo()); doFinancialAccounting(callback); } catch (Exception e) { // 业务处理失败释放幂等锁允许后续重试 bizIdempotentService.releaseIdempotent(PAY_CALLBACK, callback.getPayNo()); throw e; } }生产避坑要点幂等与分布式锁的区别分布式锁执行完立即释放控制并发幂等锁执行后保留有效期控制重复请求二者不可混用。令牌校验必须原子禁止先 GET 判断再 DEL 删除并发下会出现重复通过必须用 Lua 脚本原子执行。信号量必须释放并发限流的许可必须在 finally 中释放否则许可泄露会导致后续请求永远无法获取。幂等键唯一性业务幂等的唯一单号必须全局唯一建议前缀 业务类型 业务号组合避免不同业务冲突。
以下代码均基于 Redisson 原生 API底层全部通过 Lua 脚本保证原子性可直接接入 Spring Boot 生产项目。一、分布式限流实现提供两种生产最常用的限流方案分别对应QPS 速率控制和并发数控制两类场景。1. 令牌桶限流RRateLimiter接口 QPS 限流首选基于令牌桶算法实现原子化完成令牌生成与消耗支持平滑限流、应对突发流量是接口级限流的最优方案。适用场景接口 QPS 限制、用户级调用频次控制、第三方接口调用限流。工程化封装注解 AOP第一步自定义限流注解Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface ApiRateLimiter { // 限流业务key String key(); // 限流模式OVERALL全局总限流PER_CLIENT每个客户端独立限流 RateType mode() default RateType.OVERALL; // 单位时间内生成的令牌总数 long rate() default 10; // 时间单位 RateIntervalUnit timeUnit() default RateIntervalUnit.SECONDS; // 单次请求消耗令牌数 int permits() default 1; // 限流提示语 String msg() default 系统繁忙请稍后重试; }第二步AOP 切面实现Aspect Component public class RateLimiterAspect { Resource private RedissonClient redissonClient; Around(annotation(limiter)) public Object around(ProceedingJoinPoint joinPoint, ApiRateLimiter limiter) throws Throwable { // 组装限流key按用户限流可自行拼接userId String limitKey limit: limiter.key(); RRateLimiter rateLimiter redissonClient.getRateLimiter(limitKey); // 幂等初始化限流器重复调用不覆盖配置 rateLimiter.trySetRate(limiter.mode(), limiter.rate(), 1, limiter.timeUnit()); // 原子获取令牌成功则执行业务 boolean allow rateLimiter.tryAcquire(limiter.permits()); if (!allow) { throw new BusinessException(limiter.msg()); } return joinPoint.proceed(); } }业务使用示例// 示例1全局接口限流每秒最多20次下单请求 ApiRateLimiter(key order:create, rate 20, msg 下单人数过多请稍后重试) public String createOrder(OrderDTO dto) { // 下单业务逻辑 return ORD System.currentTimeMillis(); } // 示例2按用户限流每个用户每分钟最多调用5次查询接口 // 注按用户限流需将userId拼入key可在AOP中从上下文获取userId动态拼接 ApiRateLimiter(key user:query:order, rate 5, timeUnit RateIntervalUnit.MINUTES) public ListOrderVO queryOrderList(Long userId) { // 查询业务逻辑 return Collections.emptyList(); }关键说明RateType.OVERALL集群所有节点共享总速率适合全局接口限流。按用户 / 租户限流将用户 ID 拼入限流 key每个用户对应独立限流器实现隔离。令牌桶容量默认等于速率值支持突发流量一次性消耗存量令牌。2. 并发数限流RSemaphore 信号量基于分布式信号量控制同时持有许可的线程总数即同一时间最多有多少个线程执行指定业务。适用场景限制并发执行的任务数如导出、批量处理、保护下游资源数据库、第三方接口。工具类封装Component public class ConcurrentLimitUtil { Resource private RedissonClient redissonClient; /** * 尝试获取并发许可 * param resourceKey 资源标识 * param maxConcurrent 最大并发数 * return true获取成功false并发已满 */ public boolean tryAcquire(String resourceKey, int maxConcurrent) { RSemaphore semaphore redissonClient.getSemaphore(concurrent: resourceKey); semaphore.trySetPermits(maxConcurrent); return semaphore.tryAcquire(); } /** * 释放并发许可必须在finally中调用 */ public void release(String resourceKey) { redissonClient.getSemaphore(concurrent: resourceKey).release(); } }业务使用示例public void exportOrderData() { String resourceKey export:order; // 限制同时最多3个导出任务 if (!concurrentLimitUtil.tryAcquire(resourceKey, 3)) { throw new BusinessException(当前导出任务过多请稍后再试); } try { // 执行导出业务 doExportExcel(); } finally { // 必须释放许可防止泄露 concurrentLimitUtil.release(resourceKey); } }二、分布式幂等实现提供两种主流幂等方案分别对应前端表单防重和后端业务防重两类场景。1. 令牌式幂等表单 / 接口防重复提交前端进入页面前申请唯一令牌提交时携带令牌服务端原子校验并删除令牌校验通过才执行业务。适用场景表单重复提交、按钮重复点击、前端接口防重。工具类封装Component public class IdempotentTokenService { Resource private RedissonClient redissonClient; private static final String TOKEN_PREFIX idempotent:token:; private static final long TOKEN_EXPIRE_MINUTES 5; /** * 生成幂等令牌 * param bizId 业务标识如用户ID隔离不同主体 * return 令牌字符串 */ public String generateToken(String bizId) { String token UUID.randomUUID().toString().replace(-, ); RBucketString bucket redissonClient.getBucket(TOKEN_PREFIX bizId); bucket.set(token, TOKEN_EXPIRE_MINUTES, TimeUnit.MINUTES); return token; } /** * 原子校验并删除令牌 * return true校验通过false令牌无效/已使用 */ public boolean checkAndRemove(String bizId, String token) { String key TOKEN_PREFIX bizId; Long result redissonClient.getScript().eval( RScript.Mode.READ_WRITE, if redis.call(GET, KEYS[1]) ARGV[1] then return redis.call(DEL, KEYS[1]) else return 0 end, RScript.ReturnType.INTEGER, Collections.singletonList(key), token ); return result ! null result 1; } }业务使用流程// 1. 前端进入页面时获取令牌 GetMapping(/token/get) public ResultString getToken(RequestParam Long userId) { return Result.success(idempotentTokenService.generateToken(userId.toString())); } // 2. 提交接口校验令牌 PostMapping(/order/submit) public ResultString submitOrder( RequestHeader(idempotent-token) String token, RequestBody OrderDTO dto ) { boolean valid idempotentTokenService.checkAndRemove(dto.getUserId().toString(), token); if (!valid) { return Result.fail(请勿重复提交); } // 执行业务 String orderNo orderService.createOrder(dto); return Result.success(orderNo); }2. 业务唯一键幂等后端回调 / 消息防重以业务唯一标识作为幂等键原子加锁并保留有效期有效期内相同业务号直接拒绝重复处理。适用场景支付回调、MQ 消息重复消费、接口重试防重、重复下单控制。工具类封装Component public class BizIdempotentService { Resource private RedissonClient redissonClient; private static final String KEY_PREFIX idempotent:biz:; private static final long DEFAULT_EXPIRE_MINUTES 30; /** * 尝试获取幂等锁 * param bizType 业务类型如PAY_CALLBACK、ORDER_CREATE * param bizNo 业务唯一单号 * param expireMinutes 幂等有效期 * return true首次请求false重复请求 */ public boolean tryIdempotent(String bizType, String bizNo, long expireMinutes) { String lockKey KEY_PREFIX bizType : bizNo; RLock lock redissonClient.getLock(lockKey); try { // 等待时间为0立即返回结果持有时间为幂等有效期 return lock.tryLock(0, expireMinutes, TimeUnit.MINUTES); } catch (InterruptedException e) { Thread.currentThread().interrupt(); return false; } } public boolean tryIdempotent(String bizType, String bizNo) { return tryIdempotent(bizType, bizNo, DEFAULT_EXPIRE_MINUTES); } /** * 手动释放幂等锁业务处理失败时调用允许后续重试 */ public void releaseIdempotent(String bizType, String bizNo) { RLock lock redissonClient.getLock(KEY_PREFIX bizType : bizNo); if (lock.isHeldByCurrentThread()) { lock.unlock(); } } }业务使用示例支付回调public void handlePayCallback(PayCallbackDTO callback) { // 支付流水号作为唯一键幂等有效期30分钟 boolean isFirst bizIdempotentService.tryIdempotent(PAY_CALLBACK, callback.getPayNo(), 30); if (!isFirst) { log.info(重复支付回调直接忽略流水号{}, callback.getPayNo()); return; } try { // 执行业务更新订单状态、记账、发货等 updateOrderPayStatus(callback.getOrderNo()); doFinancialAccounting(callback); } catch (Exception e) { // 业务处理失败释放幂等锁允许后续重试 bizIdempotentService.releaseIdempotent(PAY_CALLBACK, callback.getPayNo()); throw e; } }生产避坑要点幂等与分布式锁的区别分布式锁执行完立即释放控制并发幂等锁执行后保留有效期控制重复请求二者不可混用。令牌校验必须原子禁止先 GET 判断再 DEL 删除并发下会出现重复通过必须用 Lua 脚本原子执行。信号量必须释放并发限流的许可必须在 finally 中释放否则许可泄露会导致后续请求永远无法获取。幂等键唯一性业务幂等的唯一单号必须全局唯一建议前缀 业务类型 业务号组合避免不同业务冲突。
