一、功能概述

咱们的企业知识库系统推出之后,在市场上非常受欢迎,近期有好几个公司找我购买了这个项目。

接下来,我打算再在项目中增加一些企业级的功能,让它更强大一些。

这篇文章将会实现完整的限流功能,采用「网关粗粒度兜底 + 服务内细粒度业务限流」两层设计,算法统一为 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

三、整体架构

图片.png

为什么要做两层?

层级维度解决什么问题局限
网关 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 存每次请求的时间戳,每次先移除窗口外的记录,再统计当前数量。

图片.png

整个「清理过期 → 计数 → 累加」必须放在 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
    }
}

⚠️** 类名为什么不能叫 **RedisRateLimiter

Spring Cloud Gateway 内置了一个同名类
org.springframework.cloud.gateway.filter.ratelimit.RedisRateLimiter。
网关会扫描到 kb-common,若本类与之同名,就会注册出同名 bean redisRateLimiter,
导致网关启动直接失败:

更隐蔽的是:网关那个自动配置方法上虽然标了 @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

图片.png

关键代码(维度解析部分):

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

图片.png

与业务服务保持一致,网关用的也是滑动窗口,只是 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 -count

6.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/loginIP10 次 / 60s防暴力破解(网关另有 20 次/分钟兜底)
/auth/registerIP5 次 / 300s防批量注册
/auth/password/reset/send-codeIP3 次 / 300s防验证码轰炸
/auth/password/reset/verify-codeIP10 次 / 300s防验证码爆破
/auth/password/resetIP5 次 / 300s—
/chat、/chat/streamUSER30 次 / 60sAI 对话(Token 成本控制)
/rag/chat、/rag/chat/streamUSER30 次 / 60sRAG 对话
/kag/chat、/kag/chat/streamUSER30 次 / 60s图谱推理对话
/kag/searchUSER60 次 / 60s图谱检索
/file/uploadUSER20 次 / 60s文件上传
/file/upload/batchUSER5 次 / 60s批量上传
/document/upload、/document/upload/parseUSER20 / 10 次 / 60s文档上传与解析

八、配置说明

配置项默认值说明
kb.rate-limit.enabledtrue服务内注解限流总开关(应急时可一键关闭)
kb.rate-limit.fail-opentrueRedis 异常时放行(保可用性);改 false 则拒绝(保安全)
kb.rate-limit.gateway.enabledtrue网关限流开关
kb.rate-limit.gateway.fail-opentrue网关侧 Redis 异常时的策略
kb.rate-limit.gateway.trust-forwarded-forfalse是否信任 X-Forwarded-For
kb.rate-limit.gateway.default-count0未命中规则的兜底限额,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 注解即可,无需改动限流组件

的完整限流体系。

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏