一、功能概述
咱们的企业知识库系统推出之后,在市场上非常受欢迎,近期有好几个公司找我购买了这个项目。
接下来,我打算再在项目中增加一些企业级的功能,让它更强大一些。
这篇文章将会实现完整的限流功能,采用「网关粗粒度兜底 + 服务内细粒度业务限流」两层设计,算法统一为 Redis + Lua 滑动窗口。
改造前项目里已经有一个 @RateLimit 注解,但只定义了注解、没有实现切面,也没有任何地方使用(@RateLimit 使用数为 0),网关层同样没有任何限流配置。这意味着登录接口可以被无限次暴力破解、AI 对话接口可以被脚本刷爆(每次调用都消耗大模型 Token)。
功能特性
- 两层限流:网关层按客户端 IP 兜底,业务服务内按用户/业务语义精细控制
- 四种维度:按 IP、按用户、全局限流、自动识别(登录按用户、未登录按 IP)
- 滑动窗口算法:基于 Redis + Lua 原子实现,没有固定窗口的"边界双倍突发放行"问题
- 失败开放策略:Redis 故障时默认放行(保可用性),可配置为拒绝(保安全)
- 友好提示:超限返回统一的 429 业务码,前端直接弹出注解里配置的提示语
- 标准响应头:返回
X-RateLimit-Limit/X-RateLimit-Remaining/Retry-After - 防伪造:剥离外部请求伪造的内部调用标记;IP 解析取 TCP 对端或代理链末段,防止伪造 X-Forwarded-For 绕过
二、技术栈
| 层级 | 技术 | 说明 |
|---|---|---|
| 服务内限流 | Spring AOP + 自定义注解 | @RateLimit 切面 |
| 网关限流 | Spring Cloud Gateway GlobalFilter | 全局过滤器,WebFlux 响应式 |
| 限流算法 | Redis + Lua 滑动窗口 | ZSET 存储时间戳,脚本保证原子性 |
| 服务内 Redis 客户端 | StringRedisTemplate | 阻塞式,Servlet 环境 |
| 网关 Redis 客户端 | ReactiveStringRedisTemplate | 响应式,避免阻塞事件循环 |
| 响应约定 | 统一 Result 包装 | 业务码 429 |
三、整体架构

为什么要做两层?
| 层级 | 维度 | 解决什么问题 | 局限 |
|---|---|---|---|
网关 GatewayRateLimitFilter | 客户端 IP | 挡住未登录刷接口、恶意扫描、单机压测;不依赖业务代码是否记得加注解 | 只能按 IP,同一个 NAT 出口的用户会互相影响 |
服务内 @RateLimit | 用户 / IP / 全局 | 按业务语义精细控制(如"每个用户每分钟 30 次 AI 对话"),成本控制更准 | 需要开发者在接口上显式声明 |
两者是互补关系:网关负责"别把集群打挂",服务内负责"别把某个用户/某次调用放太多"。
四、算法选型:为什么不用 INCR + EXPIRE
最朴素的固定窗口实现是 INCR 计数 + EXPIRE 过期,但它有一个致命缺陷——窗口边界双倍突发放行:
时间轴(限额 100 次 / 60 秒,固定窗口)
第 1 个窗口 第 2 个窗口
0s ────────────────────────────────────── 60s ────────────────────── 120s
▲ ▲
第 59 秒打满 100 次 第 61 秒再打 100 次
└────── 2 秒内共放行 200 次 ──────┘窗口在第 60 秒整点重置,于是第 59 秒的 100 次 + 第 61 秒的 100 次 = 2 秒内放行 200 次,
限制形同虚设。
因此本项目统一采用滑动窗口:用 Redis ZSET 存每次请求的时间戳,每次先移除窗口外的记录,再统计当前数量。

整个「清理过期 → 计数 → 累加」必须放在 Lua 脚本里执行,否则多步操作之间存在竞态,计数会偏高或偏低。
五、核心实现(kb-common)
5.1 限流维度枚举 — RateLimitType.java
package com.knowledge.base.common.annotation;
public enum RateLimitType {
/** 自动识别:已登录按用户维度,未登录按 IP 维度(默认,最实用) */
AUTO,
/** 按客户端 IP 限流(适合登录、注册、验证码等未登录接口) */
IP,
/** 按登录用户限流(适合 AI 对话、上传等已登录接口) */
USER,
/** 全局共享一个配额(适合保护下游昂贵资源,如大模型调用) */
GLOBAL
}5.2 限流注解 — RateLimit.java
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RateLimit {
/** 限流key(业务前缀)。留空时自动使用「类名.方法名」 */
String key() default "";
/** 时间窗口(秒),默认 60 秒 */
int time() default 60;
/** 时间窗口内最大请求次数,默认 100 次 */
int count() default 100;
/** 限流提示信息 */
String message() default "操作过于频繁,请稍后再试";
/** 限流维度,默认自动识别(登录用户按用户,未登录按 IP) */
RateLimitType type() default RateLimitType.AUTO;
}注解可以标在方法上,也可以标在类上(对类中所有方法生效,方法上的配置优先)。
5.3 限流结果与异常
@Data
@AllArgsConstructor
public class RateLimitResult {
/** 是否放行 */
private final boolean allowed;
/** 当前窗口内剩余可请求次数 */
private final long remaining;
/** 当前窗口内已请求次数 */
private final long currentCount;
/** 窗口大小(秒) */
private final int windowSeconds;
}public class RateLimitException extends BusinessException {
public RateLimitException(String message, String limitKey) {
super(ResultCode.TOO_MANY_REQUESTS.getCode(), message);
this.limitKey = limitKey;
}
}ResultCode 中新增业务码:
/** 请求过于频繁(限流) */
TOO_MANY_REQUESTS(429, "请求过于频繁,请稍后再试"),5.4 滑动窗口限流器 — SlidingWindowRateLimiter.java
@Slf4j
@Component("kbSlidingWindowRateLimiter")
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
public class SlidingWindowRateLimiter implements RateLimiter {
private static final String LUA_SCRIPT = """
local key = KEYS[1]
local now = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])
local member = ARGV[4]
-- 移除窗口外的历史记录
redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
local count = redis.call('ZCARD', key)
if count < limit then
redis.call('ZADD', key, now, member)
redis.call('PEXPIRE', key, window)
return {1, limit - count - 1, count + 1}
end
-- 已超限:仅续期,不再写入,避免无效数据撑大 ZSET
redis.call('PEXPIRE', key, window)
return {0, 0, count}
""";
@SuppressWarnings("rawtypes")
private static final RedisScript<List> SCRIPT =
new DefaultRedisScript<>(LUA_SCRIPT, List.class);
@Resource
private StringRedisTemplate stringRedisTemplate;
@Override
public RateLimitResult tryAcquire(String key, int limit, int windowSeconds) {
long now = System.currentTimeMillis();
long windowMillis = TimeUnit.SECONDS.toMillis(windowSeconds);
// ZSET member 需要唯一,否则同毫秒内的多个请求会互相覆盖导致漏计
String member = now + "-" + UUID.randomUUID();
List<?> result = stringRedisTemplate.execute(
SCRIPT, List.of(key),
String.valueOf(now), String.valueOf(windowMillis),
String.valueOf(limit), member);
// ... 解析结果,构造 RateLimitResult
}
}⚠️** 类名为什么不能叫 **
RedisRateLimiterSpring Cloud Gateway 内置了一个同名类
org.springframework.cloud.gateway.filter.ratelimit.RedisRateLimiter。
网关会扫描到kb-common,若本类与之同名,就会注册出同名 beanredisRateLimiter,
导致网关启动直接失败:更隐蔽的是:网关那个自动配置方法上虽然标了
@ConditionalOnMissingBean,
但它是按返回类型判断的——同名不同类的 bean 绕过了这个保护。
另外本类还额外加了@ConditionalOnWebApplication(SERVLET),
因为网关是 WebFlux 应用,本来就不该加载这个阻塞式限流器。
The bean 'redisRateLimiter' ... could not be registered.
A bean with that name has already been defined ... and overriding is disabled.5.5 限流切面 — RateLimitAspect.java

关键代码(维度解析部分):
private String resolveDimension(RateLimitType type) {
Long userId = resolveUserId();
String ip = resolveClientIp();
return switch (type) {
case GLOBAL -> "global";
// 明确要求按用户限流但取不到用户时,退回 IP,避免退化成"不限流"
case USER -> userId != null ? "user:" + userId : "ip:" + ip;
case IP -> "ip:" + ip;
// AUTO:登录用户按用户维度,未登录按 IP 维度
case AUTO -> userId != null ? "user:" + userId : "ip:" + ip;
};
}用户身份的两种来源都要兼容(不同服务的认证方式不一样):
private Long resolveUserId() {
// 1) kb-document / kb-user-auth / kb-foundation:JWT 过滤器写入 ThreadLocal
Long userId = UserContextUtil.getUserId();
if (userId != null) return userId;
// 2) kb-ai / kb-file / kb-search:只有网关透传的 X-User-Id 请求头
String headerUserId = request.getHeader("X-User-Id");
if (headerUserId != null && !headerUserId.isBlank()) {
try { return Long.parseLong(headerUserId.trim()); }
catch (NumberFormatException ignored) { return null; }
}
return null;
}IP 解析只信任"最近一跳代理写入"的地址:
private String resolveClientIp() {
// 只信任 X-Forwarded-For 的最后一段。若取第一段,客户端自带一个伪造的
// X-Forwarded-For 就能无限轮换 IP 绕过限流;网关转发时会把真实客户端
// 地址追加到末尾,因此末段才是可信的。
String forwarded = request.getHeader("X-Forwarded-For");
if (forwarded != null && !forwarded.isBlank()) {
String[] parts = forwarded.split(",");
String last = parts[parts.length - 1].trim();
if (!last.isEmpty() && !"unknown".equalsIgnoreCase(last)) {
return last;
}
}
return request.getRemoteAddr();
}六、网关层限流(kb-gateway)
6.1 为什么网关侧要用响应式 Redis
网关是 WebFlux 应用,事件循环线程不能被阻塞。因此网关的限流器必须使用 ReactiveStringRedisTemplate,而不能复用 kb-common 里那份基于 StringRedisTemplate 的阻塞式实现。
6.2 网关限流过滤器 — GatewayRateLimitFilter.java

与业务服务保持一致,网关用的也是滑动窗口,只是 Lua 脚本返回标量
(便于响应式侧解析):
-- 返回约定:> 0 放行(值为当前计数);<= 0 拒绝(值为计数的相反数)
local key = KEYS[1]
local now = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])
local member = ARGV[4]
redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
local count = redis.call('ZCARD', key)
if count < limit then
redis.call('ZADD', key, now, member)
redis.call('PEXPIRE', key, window)
return count + 1
end
redis.call('PEXPIRE', key, window)
return -count6.3 剥离伪造的内部调用头 — InternalHeaderStripFilter.java
各服务通过 INNER-REQUEST 请求头识别"服务间内部调用",并据此放宽部分校验
(例如文档级权限对内部任务放行)。但网关此前不做处理,外部客户端只要自己
带上这个头就能冒充内部调用。该过滤器在流量入口统一删除该头,
内部调用的头只会由服务间 Feign 调用重新添加:
@Component
public class InternalHeaderStripFilter implements GlobalFilter, Ordered {
private static final String INNER_REQUEST_HEADER = "INNER-REQUEST";
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
ServerHttpRequest request = exchange.getRequest();
if (request.getHeaders().containsKey(INNER_REQUEST_HEADER)) {
log.warn("拦截到外部请求伪造的内部调用标记,已剥离:uri={}, remoteIp={}", ...);
ServerHttpRequest mutated = request.mutate()
.headers(headers -> headers.remove(INNER_REQUEST_HEADER))
.build();
return chain.filter(exchange.mutate().request(mutated).build());
}
return chain.filter(exchange);
}
@Override
public int getOrder() {
return Ordered.HIGHEST_PRECEDENCE;
}
}6.4 网关限流规则配置
kb:
rate-limit:
gateway:
enabled: true
# Redis 不可用时是否放行:true=保可用性(默认),false=保安全
fail-open: true
# 是否信任 X-Forwarded-For:默认 false(网关即入口,取 TCP 对端地址,不可伪造)。
# 仅当前面还有一层可控的 Nginx/SLB 时才改为 true,届时取 XFF 的最后一段。
trust-forwarded-for: false
# 未命中任何规则时的兜底限额(0=不限制;生产可按需开启,例如 3000/60s)
default-count: 0
default-time: 60
rules:
- paths:
- /api/auth/auth/login
count: 20
time: 60
message: 登录尝试过于频繁,请 1 分钟后再试
- paths:
- /api/auth/auth/register
- /api/auth/auth/password/**
count: 10
time: 300
message: 操作过于频繁,请 5 分钟后再试
- paths:
- /api/ai/**
count: 120
time: 60
message: AI 请求过于频繁,请稍后再试
- paths:
- /api/file/files/upload
- /api/document/documents/upload
count: 60
time: 60
message: 上传过于频繁,请稍后再试⚠️** 路径要多一层,这是本项目最容易写错的地方**
网关路由
Path=/api/auth/**配了StripPrefix=2(去掉/api和/auth),
而AuthController自己又是@RequestMapping("/auth"),于是**真实外部路径是
**/api/auth/auth/login(前端auth.service.ts里也是这么调的)。同理:文件服务是
/api/file/files/**、文档服务是/api/document/documents/**。
规则里如果写成/api/auth/login,永远匹配不上,配置看起来没问题但完全不生效。
七、接入业务接口
在需要保护的接口上加一行注解即可:
@PostMapping("/login")
@Operation(summary = "用户登录")
@RateLimit(key = "auth:login", time = 60, count = 10, type = RateLimitType.IP,
message = "登录尝试过于频繁,请 1 分钟后再试")
public Result<LoginVO> login(@Valid @RequestBody LoginDTO loginDTO) { ... }当前已接入的接口:
| 接口 | 维度 | 限额 | 说明 |
|---|---|---|---|
/auth/login | IP | 10 次 / 60s | 防暴力破解(网关另有 20 次/分钟兜底) |
/auth/register | IP | 5 次 / 300s | 防批量注册 |
/auth/password/reset/send-code | IP | 3 次 / 300s | 防验证码轰炸 |
/auth/password/reset/verify-code | IP | 10 次 / 300s | 防验证码爆破 |
/auth/password/reset | IP | 5 次 / 300s | — |
/chat、/chat/stream | USER | 30 次 / 60s | AI 对话(Token 成本控制) |
/rag/chat、/rag/chat/stream | USER | 30 次 / 60s | RAG 对话 |
/kag/chat、/kag/chat/stream | USER | 30 次 / 60s | 图谱推理对话 |
/kag/search | USER | 60 次 / 60s | 图谱检索 |
/file/upload | USER | 20 次 / 60s | 文件上传 |
/file/upload/batch | USER | 5 次 / 60s | 批量上传 |
/document/upload、/document/upload/parse | USER | 20 / 10 次 / 60s | 文档上传与解析 |
八、配置说明
| 配置项 | 默认值 | 说明 |
|---|---|---|
kb.rate-limit.enabled | true | 服务内注解限流总开关(应急时可一键关闭) |
kb.rate-limit.fail-open | true | Redis 异常时放行(保可用性);改 false 则拒绝(保安全) |
kb.rate-limit.gateway.enabled | true | 网关限流开关 |
kb.rate-limit.gateway.fail-open | true | 网关侧 Redis 异常时的策略 |
kb.rate-limit.gateway.trust-forwarded-for | false | 是否信任 X-Forwarded-For |
kb.rate-limit.gateway.default-count | 0 | 未命中规则的兜底限额,0 = 不限制 |
注意:注解上的count/time是 Java 编译期常量,调整必须改代码重新发布;
而网关规则和上面这些开关在配置文件/Nacos 里,重启后生效。
如果希望运营能在配置中心改限额而不发版,可以扩展切面:让注解的key作为配置项名,
优先读取kb.rate-limit.rules.{key}覆盖注解默认值。
九、测试验证
9.1 服务端注解限流
# 连打 11 次登录(限额 10 次/分钟),第 11 次应返回 429
for i in $(seq 1 11); do
printf "第%2d次: " $i
curl -s -X POST http://localhost:8080/api/auth/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"loadtest-dummy","password":"x"}'; echo
done实测结果:
第 1次: {"code":500,"message":"用户名或密码错误,还剩4次尝试机会"}
...
第10次: {"code":500,"message":"账号已被锁定,请15分钟后再试(最多允许5次失败尝试)"}
第11次: {"code":429,"message":"登录尝试过于频繁,请 1 分钟后再试"} ← 限流生效测试时用一个不存在的用户名,避免把真实账号锁死(登录失败锁定是另一个既有功能,
5 次失败会锁定账号 15 分钟)。
总结
这套「限流功能」本质上由四部分组成:
- 限流注解:用声明式的方式把「某个接口允许多少次」表达在代码里,改接口只需加一行
- 限流器:Redis + Lua 滑动窗口的原子计数核心,解决"计数准确"的问题
- 限流切面:负责识别维度(IP / 用户 / 全局)、组装 Key、调用限流器、超限抛 429
- 网关兜底:在流量入口按 IP 拦住未登录的异常流量,同时剥离客户端伪造的内部调用标记
两层的职责边界可以这样记:
| 要解决的问题 | 由谁负责 |
|---|---|
| 集群会不会被打挂、接口会不会被扫描器刷 | 网关(IP 维度,粗粒度) |
| 某个用户是不是用得太狠、Token 成本会不会失控 | 服务内注解(用户维度,细粒度) |
| 开发新增接口时忘了加注解怎么办 | 网关兜底仍然生效 |
| 客户端伪造请求头怎么办 | 网关剥离伪造头 + IP 只取可信来源 |
只要您严格按本文的顺序实现,就能在当前项目中落地一套:
- 可防护:登录 10 次/分钟挡住暴力破解,AI 对话 30 次/分钟控制 Token 成本
- 可分级:网关按 IP 兜底 + 服务内按用户精细控制,两层互补
- 可精确:滑动窗口实现,没有固定窗口"2 秒放行 200 次"的边界突刺
- 可降级:Redis 故障时按
fail-open策略放行,业务不被限流组件拖垮 - 可观测:超限打 WARN 日志并返回
X-RateLimit-*/Retry-After响应头 - 可配置:网关规则、总开关、降级策略全部走配置文件 / Nacos
- 可扩展:新增接口加一行
@RateLimit注解即可,无需改动限流组件
的完整限流体系。