手搓了一个SpringBoot接口防护神器(防重+限流)

大家好，我是锋哥。

前言

事情是这样的，前段时间在公司项目里又写了一遍防重复提交的逻辑——Redis 加锁、拼 Key、设过期时间、处理异常释放锁……写到一半我就烦了，这套东西每个项目都要来一遍，而且每次写法还不太一样，维护起来头大。

限流也是，要么上 Sentinel 搞一套，要么自己写个拦截器糊一个，代码散得到处都是。

想了想，干脆自己封一个 Starter。搞着搞着就把防重复提交和接口限流都做了，打包发到 Maven Central 开源了。

项目叫 Guardian，一个轻量级的 Spring Boot API 请求层防护框架，目前 v1.3.0。两个功能完全独立，用哪个引哪个，互不依赖。

GitHub：

• https://github.com/BigGG-Guardian/guardian

Maven Central：

• io.github.biggg-guardian

一、防重复提交

先看效果

三步搞定：

第一步，引依赖：

<dependency><groupId>io.github.biggg-guardian</groupId><artifactId>guardian-repeat-submit-spring-boot-starter</artifactId><version>1.3.0</version></dependency>

第二步，加注解：

@PostMapping("/submit")@RepeatSubmit(interval = 10, message = "订单正在处理，请勿重复提交")public Result submitOrder(@RequestBody OrderDTO order){return orderService.submit(order);}

第三步，没了。启动项目就生效了。

10 秒内同一个用户、同一个接口、同样的请求参数，第二次请求会被直接拦截。

为什么不直接用 Redis 加个锁？

你肯定想说：”这不就是 Redis setnx 嘛，我自己写也行。”

确实能写，但你想想实际项目里会遇到的问题：

1. Key 怎么拼？

userId + url 够不够？如果同一个用户对同一个接口传了不同的参数呢？比如下单接口，买商品 A 和买商品 B 应该算两次不同的请求，不能拦截。

所以防重 Key 要把请求参数也算进去。但 POST 请求的 body 是个流，读了一次就没了，你还得处理 HttpServletRequestWrapper 的问题。

Guardian 内置了 RepeatableRequestFilter，自动缓存请求体，Key 生成时会把请求参数做 JSON 序列化 + Base64 编码拼进去。

2. 用户没登录怎么办？

很多防重方案直接用 userId 作为 Key 的一部分，但用户没登录的时候 userId 是 null，Key 就乱了。

Guardian 的处理是：已登录用 userId → 没登录用 sessionId → 没 session 用客户端 IP。三级降级，永远不会出现 null。

3. 业务异常了锁不释放怎么办？

比如用户提交订单，业务代码报了个异常，但防重锁已经设了 10 秒。结果用户修正数据重新提交，被告知”请勿重复提交”——这体验就很差了。

Guardian 在拦截器的 afterCompletion 里做了处理：如果请求抛了异常，自动释放锁。正常完成的请求才让锁自然过期。

4. 有些接口不需要防重怎么办？

全局配了防重之后，健康检查接口、公开查询接口这些也被拦了。你要么给每个接口单独控制，要么维护一个白名单。

Guardian 支持 exclude-urls 白名单，AntPath 通配符匹配，优先级最高。命中直接放行，不走任何防重逻辑。

注解不够用？试试 YAML 批量配置

单个接口用注解挺方便，但如果你有 50 个接口都要配防重，一个一个加注解就有点累了。

Guardian 支持在 YAML 里批量配置，用 AntPath 通配符一口气匹配一批接口：

guardian:repeat-submit:storage:rediskey-encrypt:md5urls:-pattern:/api/order/**interval:10key-scope:usermessage:"订单正在处理，请勿重复提交"-pattern:/api/sms/sendinterval:60key-scope:ipexclude-urls:-/api/public/**-/api/health

几个要点：

• YAML 规则的优先级高于注解，同一个接口两边都配了以 YAML 为准
• 白名单（exclude-urls）优先级最高，命中直接放行
• key-scope 控制防重维度：user（按用户）、ip（按 IP）、global（全局）

比如短信发送接口配 key-scope: ip，同一个 IP 60 秒内只能发一次，不管登没登录、哪个用户——这比按用户维度更合理。

拦截了之后怎么响应？

这是我纠结了挺久的一个设计点。

一开始只做了抛异常的方式——拦截后抛 RepeatSubmitException，让业务端的全局异常处理器去处理。但后来想到，有些项目可能就想开箱即用，不想为了一个防重还得写个异常处理器。

所以做了两种模式：

guardian:repeat-submit:response-mode:exception# 默认，抛异常# response-mode: json     # 直接返回 JSON

exception 模式（默认）： 抛 RepeatSubmitException，你在全局异常处理器里接一下：

@RestControllerAdvicepublicclassGlobalExceptionHandler{@ExceptionHandler(RepeatSubmitException.class)publicResulthandleRepeatSubmit(RepeatSubmitExceptione) {return Result.fail(e.getMessage());    }}

json 模式：拦截器直接写 JSON 响应，默认格式是 {"code":500,"msg":"...","timestamp":...}。

格式不满意？注册一个 RepeatSubmitResponseHandler Bean 就能覆盖：

@Beanpublic RepeatSubmitResponseHandler repeatSubmitResponseHandler(){return (request, response, message) -> {        response.setContentType("application/json;charset=UTF-8");        response.getWriter().write(JSONUtil.toJsonStr(R.fail(message)));    };}

不用 Redis 也能跑

不是每个项目都有 Redis 的。本地开发环境、小型单体应用，可能就没有 Redis。

guardian:repeat-submit:storage:local# 用本地缓存

切成 local 就行了，底层用 ConcurrentHashMap 实现，带定时过期清理。当然生产环境还是推荐 Redis，支持分布式。

关于 context-path 的坑

这个坑我自己踩过。项目配了 server.servlet.context-path: /admin-api，然后 YAML 里配的 URL 规则死活匹配不上。

排查了一下发现，request.getRequestURI() 返回的是带 context-path 的完整路径（比如 /admin-api/order/submit），但 YAML 里配的可能是 /order/submit。

Guardian 的处理是：匹配时同时尝试完整 URI 和去掉 context-path 后的路径，两者有一个匹配上就算命中。所以不管你 YAML 里写的是 /order/submit 还是 /admin-api/order/submit，都能正确匹配。

防重的内部流程

简单画一下请求的处理流程：

请求进入  │  ▼RepeatableRequestFilter     ← 缓存请求体，支持重复读取  │  ▼RepeatSubmitInterceptor  ├─ 1. 匹配白名单 → 命中直接放行  ├─ 2. 匹配 YAML 规则  ├─ 3. 检查 @RepeatSubmit 注解  │      均未命中 → 放行  ▼KeyGenerator                ← 按维度（user/ip/global）生成防重 Key  │  ▼KeyEncrypt                  ← 可选 MD5 加密  │  ▼Storage.tryAcquire()  ├─ 成功 → 放行，写入存储 + 设置 TTL  └─ 失败 → 根据 response-mode 响应      ├─ exception → 抛 RepeatSubmitException      └─ json → 直接写 JSON 响应  │  ▼业务执行  ├─ 正常 → Key 自然过期  └─ 异常 → afterCompletion 自动释放

二、接口限流

为什么要做限流？

防重复提交解决的是”同一个请求短时间内被提交多次”的问题，但还有另一类问题它管不了：恶意刷接口。

比如有人写个脚本一秒钟请求你的搜索接口 1000 次，防重拦不住（因为每次参数可能不一样），这时候就需要限流了。

市面上的限流方案不少，但要么是网关级别的（Sentinel、Spring Cloud Gateway），要么得写一堆配置。如果你就是个普通的 Spring Boot 单体应用，想给几个接口加个限流，没必要引那么重的东西。

Guardian 的限流就是冲着这个场景来的：轻量、注解 + YAML 双模式、两种算法可选。

先看效果

<dependency><groupId>io.github.biggg-guardian</groupId><artifactId>guardian-rate-limit-spring-boot-starter</artifactId><version>1.3.0</version></dependency>

// 滑动窗口：每秒最多 10 次@RateLimit(qps = 10)// 令牌桶：每秒补 5 个令牌，桶容量 20，允许瞬间突发 20 次@RateLimit(qps = 5, capacity = 20, algorithm = RateLimitAlgorithm.TOKEN_BUCKET)

同样支持 YAML 批量配置：

guardian:rate-limit:urls:-pattern:/api/sms/sendqps:1rate-limit-scope:ip-pattern:/api/seckill/**qps:10capacity:50algorithm:token_bucketrate-limit-scope:globalexclude-urls:-/api/public/**

和防重一样，注解 + YAML 双模式，YAML 优先级高于注解，白名单优先级最高。

滑动窗口 vs 令牌桶

这是限流最常用的两种算法，Guardian 都支持。

滑动窗口：统计时间窗口内的请求次数，超了就拒绝。比如配了 qps=10, window=1s，就是每秒最多 10 次，多了直接打回。

@RateLimit(qps = 10)

特点是严格。窗口内绝对不会超过阈值。适合短信发送、登录尝试这种需要精确控制频率的场景。

令牌桶：桶里装令牌，按固定速率往里放，请求来了取一个，桶空了就拒绝。桶满时可以一口气把令牌全用完。

@RateLimit(qps = 5, capacity = 20, algorithm = RateLimitAlgorithm.TOKEN_BUCKET)

这个配置的意思是：每秒补 5 个令牌，桶最多攒 20 个。平时空闲的时候令牌慢慢攒，突然来一波流量，瞬间可以放过 20 个请求，打完之后回到每秒 5 个的稳态。

特点是允许突发。适合秒杀、抢购这种”平时没啥流量，偶尔来一波高峰”的场景。

举个直观的例子，都是 qps=10，突然来了 20 个请求：

补充速率怎么控制？

令牌桶的补充速率通过 qps 和 window 两个参数控制：

• qps=10, window=1s → 每秒补 10 个
• qps=10, window=1min → 每分钟补 10 个（约 6 秒补 1 个）

// 每分钟补 10 个令牌，桶容量 10@RateLimit(qps = 10, window = 1, windowUnit = TimeUnit.MINUTES,        capacity = 10, algorithm = RateLimitAlgorithm.TOKEN_BUCKET)

这样就能实现慢速补充的场景。

限流维度

和防重一样，限流也支持三种维度：

@RateLimit(qps = 1, rateLimitScope = RateLimitKeyScope.IP, message = "短信发送过于频繁")

限流的响应处理

和防重一样，两种模式：

guardian:rate-limit:response-mode:exception# 默认，抛 RateLimitException# response-mode: json     # 直接返回 JSON

也支持自定义响应处理器，注册一个 RateLimitResponseHandler Bean 就行。

三、一些设计细节

并发安全

限流对并发安全的要求比防重高。你想，10 个请求同时进来，限流阈值是 5，如果并发控制没做好，可能 10 个都放过去了。

Guardian 的处理：

• Redis：滑动窗口和令牌桶都用 Lua 脚本，Redis 单线程执行 Lua 是天然原子的
• 本地缓存：synchronized 锁到 Key 粒度，不同 Key 之间互不阻塞

防重那边也是一样，Redis 用 SET NX EX 原子操作，本地缓存用 ConcurrentHashMap 的原子方法。

本地缓存的内存管理

用 ConcurrentHashMap 做本地存储有个容易忽略的问题：Key 只进不出，长时间运行内存会一直涨。

Guardian 在防重和限流的本地存储里都加了守护线程，每 5 分钟扫一次，清理过期的 Key。线程是 daemon 的，不会阻止 JVM 关闭。

可插拔架构

两个模块的核心组件都是面向接口编程的，框架内部用 @ConditionalOnMissingBean 做的，你不注册就用默认的，注册了就用你的：

可观测性

两个模块都内置了监控能力：

拦截日志：log-enabled: true 开启后，拦截/放行都有日志输出。

Actuator 端点：

GET /actuator/guardian-repeat-submit    → 防重统计GET /actuator/guardian-rate-limit       → 限流统计

限流的统计数据长这样：

{"totalRequestCount": 5560,"totalPassCount": 5432,"totalBlockCount": 128,"blockRate": "2.30%","topBlockedApis": { "/api/sms/send": 56 },"topRequestApis": { "/api/search": 3200 }}

项目结构

guardian-parent├── guardian-core                          # 公共基础（共享类）├── guardian-repeat-submit/                # 防重复提交│   ├── guardian-repeat-submit-core/│   └── guardian-repeat-submit-spring-boot-starter/├── guardian-rate-limit/                   # 接口限流│   ├── guardian-rate-limit-core/│   └── guardian-rate-limit-spring-boot-starter/├── guardian-storage-redis/                # Redis 存储（多模块共享）└── guardian-example/                      # 示例工程

模块拆分是为了灵活组合。比如你只需要防重就引 guardian-repeat-submit-spring-boot-starter，只需要限流就引 guardian-rate-limit-spring-boot-starter，都需要就两个都引，互不影响。

guardian-core 放的是两个模块都用到的公共类，比如 UserContext、GuardianResponseHandler。guardian-storage-redis 是 Redis 存储的共享实现，两个模块的 Redis 存储都在这里面。

总结

Guardian 做了两件事：

1. 防重复提交：拦截短时间内的重复请求，支持注解 / YAML、用户 / IP / 全局维度、异常自动释放、context-path 兼容
2. 接口限流：控制接口访问频率，支持滑动窗口 / 令牌桶、突发流量处理、三种维度

两个功能独立 Starter，核心组件全部可插拔，注册 Bean 就能替换默认实现。Redis 和本地缓存一键切换。

如果你的 Spring Boot 项目里需要这些能力，但又不想引 Sentinel 那么重的东西，可以试试。

Maven Central 坐标：

<!-- 防重复提交 --><dependency><groupId>io.github.biggg-guardian</groupId><artifactId>guardian-repeat-submit-spring-boot-starter</artifactId><version>1.3.0</version></dependency><!-- 接口限流 --><dependency><groupId>io.github.biggg-guardian</groupId><artifactId>guardian-rate-limit-spring-boot-starter</artifactId><version>1.3.0</version></dependency>