SpringBoot AOP Redis 接口限流注解示例代码

限流是后端服务保护的第一道防线。通过Spring Boot中AOP切面编程结合Redis，我们可以轻松实现一个自定义注解，只需在接口上添加即可生效——这听起来简单，但在实际落地中需要考虑诸多细节。本文将详细拆解这一方案，从原理到实践，帮助你全面掌握基于SpringBoot AOP和Redis的接口限流注解实现。

一、限流注解的定义与属性配置

首先，我们需要定义限流注解的属性。核心字段包括：限流键（key）、限流维度（支持按用户、按IP、按接口三种模式）、窗口内最大请求数（max）、窗口大小（window，单位为秒），以及被限流时的提示信息（message）。这样的设计具有良好的扩展性，便于后续根据业务需求调整。

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RateLimit {

    /** 限流 key */
    String key() default "";

    /** 限流维度：user / ip / api */
    String type() default "user";

    /** 窗口内最大请求数 */
    long max() default 10;

    /** 窗口大小（秒） */
    long window() default 1;

    /** 被限后的提示 */
    String message() default "请求太频繁，请稍后重试";
}

二、AOP切面实现限流逻辑

注解定义完成后，接下来实现核心逻辑。通过AOP切面拦截所有标注了@RateLimit的方法，利用Redis的有序集合（ZSet）实现滑动窗口限流算法。关键点在于使用Lua脚本保证操作的原子性，避免高并发场景下的计数误差。

@Aspect
@Component
public class RateLimitAspect {

    @Autowired
    private StringRedisTemplate redisTemplate;

    @Around("@annotation(rateLimit)")
    public Object around(ProceedingJoinPoint pjp, RateLimit rateLimit) throws Throwable {
        String key = buildKey(rateLimit);

        // 滑动窗口限流
        boolean allowed = tryAcquire(key, rateLimit.max(), rateLimit.window());

        if (!allowed) {
            throw new BusinessException(429, rateLimit.message());
        }

        return pjp.proceed();
    }

    private boolean tryAcquire(String key, long max, long windowSec) {
        long now = System.currentTimeMillis();
        long windowMs = windowSec * 1000L;
        long windowStart = now - windowMs;

        // Lua 脚本保证原子性
        String lua =
            "redis.call('ZREMRANGEBYSCORE', KEYS[1], 0, ARGV[1]) " +
            "local count = redis.call('ZCARD', KEYS[1]) " +
            "if count < tonumber(ARGV[2]) then " +
            "  redis.call('ZADD', KEYS[1], ARGV[3], ARGV[3]) " +
            "  redis.call('EXPIRE', KEYS[1], ARGV[4]) " +
            "  return 1 " +
            "else " +
            "  return 0 " +
            "end";

        Long result = redisTemplate.execute(
            new DefaultRedisScript<>(lua, Long.class),
            Collections.singletonList(key),
            String.valueOf(windowStart),
            String.valueOf(max),
            String.valueOf(now),
            String.valueOf(windowSec + 1)
        );

        return Long.valueOf(1).equals(result);
    }

    private String buildKey(RateLimit rateLimit) {
        String prefix = "rate:";

        switch (rateLimit.type()) {
            case "ip":
                HttpServletRequest request = ((ServletRequestAttributes)
                    RequestContextHolder.getRequestAttributes()).getRequest();
                return prefix + "ip:" + getIp(request);
            case "api":
                return prefix + "api:" + Stream.of(
                    Thread.currentThread().getStackTrace())
                    .filter(s -> s.getMethodName().contains("$"))
                    .findFirst().orElse(new StackTraceElement("", "", "", 0))
                    .getMethodName();
            default:
                // type = user
                return prefix + "user:" + StpUtil.getLoginIdAsString();
        }
    }

    public static String getIp(HttpServletRequest request) {
        String ip = request.getHeader("X-Forwarded-For");
        if (ip == null || ip.isEmpty()) ip = request.getHeader("X-Real-IP");
        if (ip == null || ip.isEmpty()) ip = request.getRemoteAddr();
        if (ip != null && ip.contains(",")) ip = ip.split(",")[0].trim();
        return ip;
    }
}

三、在Controller中集成注解

使用方式非常简洁：只需在Controller接口方法上添加@RateLimit注解，并指定限流维度与参数即可。例如，对一个GET接口限制每个IP在10秒内最多5次请求，或对秒杀接口限制每个用户10秒内仅能请求1次，有效防止刷单。

@RestController
@RequestMapping("/api")
public class TestController {

    @GetMapping("/test")
    @RateLimit(key = "test", type = "ip", max = 5, window = 10)
    public ResultVO test() {
        return ResultVO.success("成功");
    }

    @PostMapping("/seckill/{productId}")
    @RateLimit(type = "user", max = 1, window = 10)
    public ResultVO seckill(@PathVariable Long productId) {
        return ResultVO.success("秒杀成功");
    }
}

四、全局异常处理与友好提示

当请求被限流时，切面会抛出BusinessException异常。因此，我们需要配置一个全局异常处理器来捕获该异常，并返回HTTP 429状态码及对应的提示信息。这样前端可以根据状态码进行友好的用户提示，避免直接崩溃。

@RestControllerAdvice
public class RateLimitExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public ResultVO handleBusiness(BusinessException e) {
        if (e.getMessage().contains("请求太频繁")) {
            return ResultVO.error(429, e.getMessage());
        }
        return ResultVO.error(e.getCode(), e.getMessage());
    }
}

五、压测验证与效果展示

效果如何？通过压力测试验证。使用curl模拟20个并发请求，结果清晰可见：前5个请求正常返回，后续所有请求均被拦截，返回429状态码和限流提醒。限流策略稳定可靠，有效保护后端接口。

# 模拟 20 个并发请求
for i in {1..20}; do
    curl -X GET http://localhost:9090/api/test &
done

# 正常响应：{"code":200,"message":"成功"}
# 被限响应：{"code":429,"message":"请求太频繁，请稍后重试"}