[017][web模块]基于计数器的接口幂等性与访问限流设计实战
本项目代码:https://gitee.com/yunjiao-source/tutorials4j/tree/master/framework
在分布式系统中，接口的幂等性保障和访问频率限制是两个常见且重要的需求。本文介绍一套轻量级、基于 Redis 计数器的实现方案，通过自定义注解、拦截器和缓存模板，为 Spring MVC 应用提供声明式的幂等控制与限流能力。
一、功能概览
本方案提供两个核心能力：
- 接口幂等性：确保同一请求在有效期内只被成功处理一次，防止重复提交。
- 访问频率限制：限制同一请求方在单位时间内的访问次数，防止恶意刷接口或超出配额调用。
两者均基于“计数”逻辑：幂等要求最大计数为 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 来缩小范围，避免不必要的性能损耗。
六、总结
本文介绍的基于计数器的幂等与限流方案，具有以下优点：
- 实现简洁：核心逻辑集中在抽象模板中，易于理解和维护。
- 声明式使用：通过注解即可快速为接口增加保护，对业务代码无侵入。
- 扩展性好：可轻松调整最大次数、键生成方式、缓存有效期等。
同时也存在改进空间：原子计数、过期策略的完善以及更灵活的限流算法（令牌桶、漏桶）。开发者可根据实际场景在此基础上进行二次开发。
该方案已经应用于多个内部项目，稳定地保障了接口的正确性与系统的可用性。希望本文能为您的分布式接口治理提供参考。
