限流不是加个计数器就行：用 Lua 脚本实现多维度原子限流

限流不是加个计数器就行用 Lua 脚本实现多维度原子限流项目地址interview-agent技术栈Java 21 / Spring Boot 4.0 / Redis 7 (Redisson) / PostgreSQL问题单维度限流挡不住真实场景简历上传接口你加了一个每分钟 10 次的限流。上线第一天就出事了正常用户被误杀。某个 IP 后面有 20 个用户共享出口 IP公司 NAT一个人疯狂上传其他人全部 429。恶意用户绕过限流。攻击者切换 IP 继续上传全局限流形同虚设——每个 IP 都没超但总量已经把 LLM 配额打爆了。部分扣减导致数据不一致。你用两段式代码先检查 IP 限流再检查全局限流IP 通过了、全局没通过但 IP 的计数器已经加了。等全局恢复后IP 的限流凭空少了一个名额。这三个问题指向同一个根因单维度、非原子的限流方案在多维度组合场景下必然出错。这篇文章记录了 Interview Agent 项目怎么用一个 Lua 脚本 一个 AOP 切面实现声明式、多维度、原子性的限流。整体方案┌─────────────────────────────────────────────────────┐ │ RateLimit(dimensions {GLOBAL, IP}, count 5) │ ← 声明式注解 └─────────────┬───────────────────────────────────────┘ │ AOP 拦截 ▼ ┌─────────────────────────────────────────────────────┐ │ RateLimitAspect │ │ 1. 计算时间窗口毫秒 │ │ 2. 按维度生成 Redis Key 列表 │ │ 3. 调用 Lua 脚本evalSha │ │ 4. 结果1 → 放行 结果0 → 降级/拒绝 │ └─────────────┬───────────────────────────────────────┘ │ evalSha原子执行 ▼ ┌─────────────────────────────────────────────────────┐ │ Lua 脚本Redis 服务端执行 │ │ ┌───────────────┐ ┌───────────────────┐ │ │ │ 第一阶段预检查 │───▶│ 第二阶段扣减令牌 │ │ │ │ 所有维度都够 │ │ 所有维度一起扣 │ │ │ └───────────────┘ └───────────────────┘ │ └─────────────────────────────────────────────────────┘三个组件各司其职组件职责位置RateLimit注解声明维度、阈值、降级方法Controller 方法上RateLimitAspectAOP 拦截、Key 生成、结果处理common/aspect/rate_limit.lua原子检查 扣减resources/scripts/注解设计声明式限流Target(ElementType.METHOD)Retention(RetentionPolicy.RUNTIME)publicinterfaceRateLimit{enumDimension{GLOBAL,IP,USER}Dimension[]dimensions()default{Dimension.GLOBAL};doublecount();// 窗口内最大请求数longinterval()default1;// 时间窗口大小TimeUnittimeUnit()defaultTimeUnit.SECONDS;longtimeout()default0;// 等待令牌超时0不等待Stringfallback()default;// 降级方法名}使用时只需要一行注解PostMapping(/api/resumes/upload)RateLimit(dimensions{GLOBAL,IP},count5)publicResultMapString,ObjectuploadAndAnalyze(RequestParam(file)MultipartFilefile){// ...}这行注解的语义是全局每秒最多 5 次同时每个 IP 每秒最多 5 次两个维度都满足才放行。项目里还有更精细的配置// 知识库查询全局 10/min单 IP 10/minRateLimit(dimensions{GLOBAL,IP},count10)// 简历重新分析全局 2/min单 IP 2/minLLM 调用昂贵RateLimit(dimensions{GLOBAL,IP},count2)// 面试答题仅全局限流用户已经登录不需要 IP 维度RateLimit(dimensions{GLOBAL},count10)Lua 脚本两阶段原子执行这是整个方案的核心。为什么用 Lua因为 Redis 的单线程模型保证了 Lua 脚本的原子性——脚本执行期间不会有其他命令插入。数据结构每个维度在 Redis 里有两个 Keyratelimit:{ClassName:methodName}:global:value → 当前可用令牌数String ratelimit:{ClassName:methodName}:global:permits → 已分配令牌记录Sorted Setpermits是一个 Sorted Setmember 是requestId:permitsscore 是分配时间戳毫秒。这个结构支持精确的过期回收。第一阶段预检查fori,keyinipairs(KEYS)dolocalvalue_keykey..:valuelocalpermits_keykey..:permits-- 初始化首次访问时令牌满额ifredis.call(exists,value_key)0thenredis.call(set,value_key,max_tokens)end-- 回收过期令牌localexpired_valuesredis.call(zrangebyscore,permits_key,0,now_ms-interval)if#expired_values0thenlocalexpired_count0for_,vinipairs(expired_values)dolocalptonumber(string.match(v,:(%d)$))ifpthenexpired_countexpired_countpendendredis.call(zremrangebyscore,permits_key,0,now_ms-interval)localnext_vmath.min(max_tokens,curr_vexpired_count)redis.call(set,value_key,next_v)end-- 核心令牌够不够ifcurrent_valpermitsthenreturn0-- 任何一个维度不够直接返回失败endend关键点过期回收在检查前执行。这意味着每次请求都会顺带清理过期令牌不需要定时任务。math.min(max_tokens, ...)防止回收后令牌超过上限——Sorted Set 里可能有重复或过期的记录。第二阶段扣减fori,keyinipairs(KEYS)dolocalvalue_keykey..:valuelocalpermits_keykey..:permits-- 记录本次分配redis.call(zadd,permits_key,now_ms,request_id..:..permits)-- 扣减令牌redis.call(set,value_key,current_v-permits)-- 设置过期时间窗口的 2 倍至少 1 秒redis.call(expire,value_key,expire_time)redis.call(expire,permits_key,expire_time)endreturn1只有第一阶段所有维度都通过才会进入第二阶段。这解决了前面提到的部分扣减问题——不存在IP 扣了但全局没扣的中间状态。Key 生成Redis Cluster 兼容privateListStringgenerateKeys(StringclassName,StringmethodName,RateLimit.Dimension[]dimensions){StringhashTag{className:methodName};StringkeyPrefixratelimit:hashTag;for(RateLimit.Dimensiondimension:dimensions){switch(dimension){caseGLOBAL-keys.add(keyPrefix:global);caseIP-keys.add(keyPrefix:ip:getClientIp());caseUSER-keys.add(keyPrefix:user:getCurrentUserId());}}returnkeys;}{ClassName:methodName}是 Redis Cluster 的 Hash Tag。在 Cluster 模式下Redis 只对{}内的部分做 slot 计算。这意味着同一个方法的所有维度 Keyglobal、ip:1.2.3.4、user:42都会落在同一个 slot 上保证 Lua 脚本可以在单个节点上原子执行。如果没有这个 Hash Tagratelimit:upload:global和ratelimit:upload:ip:1.2.3.4可能落在不同 slotLua 脚本会报CROSSSLOT错误。降级策略不是只有拒绝限流触发时有两种处理方式privateObjecthandleRateLimitExceeded(ProceedingJoinPointjoinPoint,RateLimitrateLimit,ListStringkeys){// 1. 有降级方法调用降级方法if(!rateLimit.fallback().isEmpty()){MethodfallbackMethodfindFallbackMethod(joinPoint,rateLimit.fallback());if(fallbackMethod!null){returnfallbackMethod.invoke(joinPoint.getTarget(),joinPoint.getArgs());}}// 2. 没有降级方法抛异常thrownewRateLimitExceededException(请求过于频繁请稍后再试);}降级方法的查找规则先找同参数签名的找不到找无参的。这允许降级方法根据原始请求参数做更精细的处理比如返回缓存数据也允许简单的返回默认值场景。// 原方法RateLimit(count5,fallbackqueryFallback)publicResultQueryResponsequery(QueryRequestrequest){...}// 降级方法返回缓存或默认值publicResultQueryResponsequeryFallback(QueryRequestrequest){returnResult.success(cachedService.getLastResult(request));}Script 预加载PostConstructpublicvoidinit(){this.luaScriptSharedissonClient.getScript(StringCodec.INSTANCE).scriptLoad(LUA_SCRIPT);}scriptLoad把 Lua 脚本上传到 Redis返回一个 SHA1 摘要。后续调用用evalSha传 SHA1 而不是完整脚本内容减少了网络传输量。Redis 会缓存脚本evalSha的执行效率和原生命令一样。如果 Redis 重启导致脚本缓存丢失evalSha会返回NOSCRIPT错误。目前代码没有处理这个边界情况——在单实例部署下 Redis 重启意味着服务也会重启PostConstruct会重新加载脚本。设计哲学1. 原子性不是靠代码顺序是靠执行环境Java 代码里的先检查再扣减在并发下是不安全的——两个线程可能同时检查通过然后各扣一个实际消耗了 2 个令牌但只限制了 1 个。分布式锁可以解决但性能太差。Lua 脚本在 Redis 单线程里执行天然原子不需要额外的锁。2. 多维度是 AND 语义不是 ORdimensions {GLOBAL, IP}的含义是全局且每个 IP 都不能超。如果用 OR 语义任一维度通过即可攻击者可以利用维度差异绕过限流。AND 语义下最严格的维度决定最终结果。3. 声明式优于编程式限流逻辑不应该和业务代码混在一起。一行注解RateLimit(count 5)比在方法开头写 20 行限流代码更清晰、更不容易出错、更容易统一修改。AOP 的开销一次方法拦截 一次 Redis 调用相比 LLM 调用的耗时可以忽略。4. 降级优于拒绝限流不是为了惩罚用户是为了保护系统。如果能返回缓存数据、默认值、或者排队提示比直接返回 429 体验好得多。fallback机制让每个接口可以定义自己的降级策略。5. Key 设计要考虑部署拓扑单机 Redis 随便怎么写 Key 都行。但一旦上了 ClusterKey 的 slot 分配就变成了正确性问题——Lua 脚本要求所有 Key 在同一个 slot。{hashTag}是 Redis Cluster 的标准做法应该从一开始就用而不是等迁移到 Cluster 时再改。局限性没有令牌桶/漏桶算法。当前实现是固定窗口计数器窗口边界处可能出现突发流量窗口末尾 5 次 下个窗口开头 5 次 1 秒内 10 次。令牌桶可以平滑流量但 Lua 脚本复杂度会显著增加。IP 获取依赖 HTTP 头。X-Forwarded-For和X-Real-IP可以被客户端伪造。在没有反向代理覆盖这些头的场景下IP 限流不可靠。timeout参数未实现。注解里声明了timeout字段等待令牌的超时时间但当前 Lua 脚本没有实现阻塞等待逻辑——令牌不够就直接返回失败。没有分布式限流的监控。限流触发次数、各维度的令牌消耗率、降级方法的调用频率——这些指标目前没有采集。线上只能靠日志排查限流问题。Script 重加载未处理。Redis 重启后 SHA1 失效evalSha会失败。需要 catchNOSCRIPT错误并自动重新加载脚本。结语限流看起来简单——加个计数器超了就拒绝。但在多维度、分布式、需要原子性的场景下简单的方案会暴露出各种竞态和一致性问题。Lua 脚本把检查和扣减放在 Redis 服务端一次性完成AOP 把限流逻辑从业务代码里抽离出来注解把配置变成了声明。三层分离各解决一个问题。如果你的项目已经有 Redis需要给几个关键接口加上限流不需要引入 Sentinel 或 Resilience4j 这样的重量级框架——一个 Lua 脚本 一个切面就够了。本文代码来自 Interview Agent 项目common/annotation/、common/aspect/和resources/scripts/目录关键文件RateLimit.java、RateLimitAspect.java、rate_limit.lua。