[017][web模块]基于计数器的接口幂等性与访问限流设计实战

本项目代码:https://gitee.com/yunjiao-source/tutorials4j/tree/master/framework

在分布式系统中，接口的幂等性保障和访问频率限制是两个常见且重要的需求。本文介绍一套轻量级、基于 Redis 计数器的实现方案，通过自定义注解、拦截器和缓存模板，为 Spring MVC 应用提供声明式的幂等控制与限流能力。

一、功能概览

本方案提供两个核心能力：

1. 接口幂等性：确保同一请求在有效期内只被成功处理一次，防止重复提交。
2. 访问频率限制：限制同一请求方在单位时间内的访问次数，防止恶意刷接口或超出配额调用。

两者均基于“计数”逻辑：幂等要求最大计数为 1（首次成功，后续拒绝），限流则允许配置更大的上限（例如 10 次/分钟）。计数器的存储依托 Redis，实现高性能与分布式一致性。

二、核心设计思想

2.1 统一计数器抽象

三个核心类构成计数器体系：

• AbstractCounterCacheTemplate：抽象模板，封装 Redis 计数器的通用逻辑（自增、上限校验、键值处理等）。
• IdempotentCacheTemplate：专用于幂等性，构造时 maxTimes = 1。
• AccessLimitedCacheTemplate：专用于访问限制，maxTimes 由注解动态指定。

这样的继承层次使得通用逻辑只需实现一次，不同业务仅需调整上限参数。

2.2 注解 + 拦截器实现声明式控制

• @Idempotent：标记需要幂等校验的方法。
• @AccessLimited：标记需要限流的方法，可通过 maxTimes() 指定最大访问次数。

两个拦截器分别处理上述注解，在 preHandle 阶段生成请求的唯一标识，并调用对应的计数器模板进行计数。若计数失败（超过上限），则抛出特定业务异常，由全局异常处理器返回适当响应。

2.3 请求唯一键生成

SessionUtils.generateRequestKey(request) 负责生成标识一个请求的字符串。典型的组成方式包括：

• 用户 session ID 或 JWT 中的用户 ID
• 请求 URI
• 请求参数（JSON 或 form 参数可序列化后取摘要）
• IP 地址等

该键保证了不同用户、不同接口、不同参数的请求能够被正确区分。

2.4 键 MD5 摘要（可选）

AbstractCounterCacheTemplate.counting 提供了一个 useMd5 参数。当原始键可能过长或含有特殊字符时，可使用 MD5 缩短并规范化键名，节省 Redis 内存。

三、关键代码解析

3.1 抽象计数器模板

public abstract class AbstractCounterCacheTemplate extends AbstractRedisCacheTemplate<String, Integer> {
   
    private int maxTimes = 1;

    public int counting(String key, int maxTimes, boolean useMd5) {
   
        // 1. 校验与键值转换
        String newKey = useMd5 ? SecureUtil.md5(key) : key;
        Integer current = get(newKey);
        if (current == null) current = 0;

        // 2. 首次访问则创建缓存值为1
        if (current == 0) {
   
            create(newKey);
        } else {
   
            // 3. 已达上限则抛异常
            if (current >= maxTimes) {
   
                throw new CounterOverflowException(maxTimes);
            }
            put(newKey, current + 1);
        }
        return current + 1;
    }
}

注意：create(newKey) 会调用 valueGenerator(key) 返回初始值 1，因此首次计数后缓存值为 1。后续每次调用加 1，直到达到 maxTimes。

3.2 幂等拦截器

public class IdempotentHandlerInterceptor implements HandlerInterceptor {
   
    private final IdempotentCacheTemplate idempotentCacheTemplate;

    @Override
    public boolean preHandle(HttpServletRequest request, ...) {
   
        // 获取方法上的 @Idempotent 注解
        Idempotent idempotent = method.getAnnotation(Idempotent.class);
        if (idempotent != null) {
   
            String key = SessionUtils.generateRequestKey(request);
            idempotentCacheTemplate.counting(key);  // maxTimes 固定为1
        }
        return true;
    }
}

3.3 限流拦截器

与之类似，但传入注解中配置的 maxTimes：

AccessLimited limited = method.getAnnotation(AccessLimited.class);
if (limited != null) {
   
    accessLimitedCacheTemplate.counting(key, limited.maxTimes());
}

3.4 自动配置

SecurityConfiguration 实现 WebMvcConfigurer，将两个拦截器注册到 Spring MVC 的拦截器链中。由于使用了 @Configuration(proxyBeanMethods = false)，该配置会被 Spring Boot 自动扫描加载（通常通过 META-INF/spring.factories 或 @Import 控制）。

四、使用示例

4.1 添加依赖与配置

确保项目中已引入 Redis 相关依赖以及本框架。在 application.yml 中配置 Redis 连接信息（继承自 AbstractRedisCacheTemplate 的底层配置即可）。

4.2 编写 Controller 并添加注解

@RestController
public class OrderController {
   

    @PostMapping("/order")
    @Idempotent   // 防止重复下单
    public Result createOrder(@RequestBody OrderReq req) {
   
        // 业务逻辑...
    }

    @GetMapping("/search")
    @AccessLimited(maxTimes = 5)  // 每分钟最多5次
    public Result search(String keyword) {
   
        // 搜索逻辑...
    }
}

4.3 异常处理

当重复请求或超出限流阈值时，拦截器会分别抛出 IdempotentException 和 AccessLimitedException。可定义 @RestControllerAdvice 统一返回错误码与提示信息，例如：

@ExceptionHandler(IdempotentException.class)
public ResponseEntity<String> handleIdempotent() {
   
    return ResponseEntity.status(409).body("重复请求，请勿重试");
}

五、扩展与注意事项

5.1 缓存有效期

当前的计数缓存没有设置过期时间。这意味着一旦计数达到上限，将永久拒绝后续请求。实际生产环境中，通常需要配合过期策略：

• 幂等性：建议对缓存设置合理的过期时间（如 5 分钟、1 小时），由 AbstractRedisCacheTemplate 的 expire 方法支持。
• 访问限制：典型的限流是滑动窗口或固定窗口计数器，应设置窗口过期时间（如 1 分钟）。

可以在创建缓存时调用 redisTemplate.expire(key, timeout, unit) 来添加 TTL。

5.2 分布式环境下的原子性

AbstractCounterCacheTemplate 中的 get、create、put 操作并非严格原子。极端并发下可能造成计数不准确。改进方案是使用 Redis 的 INCR 命令，该命令原生支持原子递增，并且可以检查返回值是否超过上限。当前实现适合并发不高的场景，若需高并发精确限流，建议改用 RedisAtomicLong 或 Lua 脚本。

5.3 键的生成策略

SessionUtils.generateRequestKey 的实现决定了安全性与覆盖面。例如：

• 仅根据用户 ID + URI 可以防止同一用户的重复提交，但无法区分不同参数。
• 加入请求体摘要可区分不同内容，但会降低缓存命中率。

开发者应根据业务需要重写该方法，或通过配置声明键的组成规则。

5.4 与 Spring 生态的整合

本方案拦截器默认对所有请求路径生效。可以通过配置 addInterceptor 时指定 addPathPatterns 和 excludePathPatterns 来缩小范围，避免不必要的性能损耗。

六、总结

本文介绍的基于计数器的幂等与限流方案，具有以下优点：

• 实现简洁：核心逻辑集中在抽象模板中，易于理解和维护。
• 声明式使用：通过注解即可快速为接口增加保护，对业务代码无侵入。
• 扩展性好：可轻松调整最大次数、键生成方式、缓存有效期等。

同时也存在改进空间：原子计数、过期策略的完善以及更灵活的限流算法（令牌桶、漏桶）。开发者可根据实际场景在此基础上进行二次开发。

该方案已经应用于多个内部项目，稳定地保障了接口的正确性与系统的可用性。希望本文能为您的分布式接口治理提供参考。