如何实现多维API限流：interview-guide 可重复注解 + Redis Lua 完整指南

如何实现多维API限流interview-guide 可重复注解 Redis Lua 完整指南【免费下载链接】interview-guide基于 Spring Boot 4.1、Java 25、Spring AI 2.0、React、PostgreSQL/pgvector、Redis 和 RustFS 构建的开源 AI 面试平台支持简历智能分析、模拟面试、语音面试和知识库 RAG。项目地址: https://gitcode.com/gh_mirrors/inter/interview-guideinterview-guide 是一个开源 AI 面试平台它的RateLimit可重复注解配合 Redis Lua 脚本让开发者只需两三行注解就能同时完成Global全局/ IP / User用户三个维度的 API 限流且多维度检查在一次 Redis 调用中原子完成。本文将从设计动机讲到落地细节带你完整看懂这套限流方案。为什么需要多维 API 限流单一维度的限流往往顾此失彼只限全局一个疯狂刷接口的用户会占满整个服务的配额其他用户全部被连坐只限 IPNAT 出口如公司网络、校园网下大量真实用户共享一个 IP容易被误伤只限用户游客/匿名请求无法按用户区分恶意流量照样能打满服务。✅ 正确姿势是多维度叠加全局限流守住服务总容量IP 限流挡住刷接口行为User 限流约束单用户频率。interview-guide 正是这样做的。核心设计 1可重复注解 RateLimit三条规则各管一个维度限流注解定义在 RateLimit.java。它的精髓是Repeatable(RateLimit.Container.class)——同一个方法上可以标注多条相互独立的限流规则PostMapping(/api/resumes/upload) RateLimit(dimension RateLimit.Dimension.GLOBAL, count 5) // 全局每秒最多 5 次 RateLimit(dimension RateLimit.Dimension.IP, count 5) // 单 IP每秒最多 5 次 public ResultMapString, Object uploadAndAnalyze(...) { ... }这条真实用例来自简历上传接口 ResumeController.java上传简历会触发一次耗费的 LLM 分析全局和单 IP 各设 5 次/秒而成本更高的重新分析接口 reanalyze 则收紧到 2 次/秒。每条规则支持独立的配置项非常灵活属性含义默认值dimension限流维度GLOBAL / IP / USERGLOBALcount时间窗口内允许的最大请求数支持小数如 0.5 每 2 秒 1 次必填intervaltimeUnit时间窗口支持毫秒/秒/分/时/天1 秒timeout是否等待令牌0 表示立即拒绝0fallback限流触发时调用的降级方法名抛出限流异常 所有规则全部通过才放行请求——任何一个维度超限都会拦截。核心设计 2Redis Lua 滑动窗口多条规则一次原子扣减限流的检查 扣减逻辑全部写在 Lua 脚本里rate_limit_single.lua。为什么必须用 LuaRedis 的先 GET 再 SET两步操作在高并发下存在竞态两个请求可能同时读到还有令牌导致实际放行量超配额。Lua 脚本在 Redis 内部单线程原子执行天然消除竞态无需分布式锁。脚本采用经典的滑动窗口算法比固定窗口更平滑不会出现窗口边缘 2 倍突发第一阶段——只读检查遍历每条规则的KEYS[i]从有序集合中统计滑出窗口的历史令牌恢复已归还的额度若任一维度余量不足立即返回-ii为失败规则的下标不修改任何状态第二阶段——统一扣减所有维度都通过后才把本次请求的令牌写入各维度的有序集合并更新余量同时设置过期时间自动清理。这套先全部校验、后统一提交的两阶段设计很关键如果只扣了一半就发现另一个维度超了就会出现额度白扣的脏状态。核心设计 3AOP 切面把一切串起来RateLimitAspect.java 用Around环绕通知拦截所有带注解的方法负责把注解翻译成一次 Lua 调用一次网络往返搞定所有维度所有规则的 key 打包进KEYS所有参数打包进ARGV一次EVALSHA完成检查扣减避免 N 条规则产生 N 次 Redis 交互Hash Tag 保证同槽位key 统一使用ratelimit:{类名:方法名}:维度:值的格式Redis Cluster 模式下所有维度键落在同一 slot满足 Lua 多 key 原子执行的要求NOSCRIPT 自愈Redis 重启会清空脚本缓存切面捕获NOSCRIPT异常后自动重新SCRIPT LOAD并重试无需人工介入真实的客户端 IP依次解析X-Forwarded-For、X-Real-IP等多个代理头兼容多种网关部署User 维度则从请求属性或X-User-Id头中提取用户 ID。Lua 脚本在启动时通过PostConstruct预加载并缓存 SHA1运行期直接用EVALSHA执行比EVAL传输完整脚本体更省带宽。限流触发后优雅降级而不是生硬报错被拦截的请求有两条出路都由注解的fallback属性控制handleRateLimitExceeded配置了降级方法反射调用同类中的降级方法无参或参数签名与原方法一致比如返回缓存结果或友好提示未配置抛出 RateLimitExceededException由全局异常处理器统一转换为标准错误响应错误码8001提示请求过于频繁请稍后再试见 ErrorCode.java。方案速览一张表总结关注点实现手段多规则声明Repeatable可重复注解规则间完全独立三维度限流GLOBAL / IP / USER 枚举 动态 key 拼接原子性Redis Lua 两阶段滑动窗口脚本性能一次EVALSHA完成全部维度Hash Tag 保证同 slot高可用NOSCRIPT 自动重载脚本key 自动过期清理友好处理fallback 降级方法 / 统一异常码 8001结语interview-guide 的限流方案给了一个很好的示范声明式注解负责说什么Lua 脚本负责怎么算AOP 切面负责何时执行三层各司其职。对于任何使用 Redis 的 Java 项目这套可重复注解 Lua 滑动窗口的模式都可以直接借鉴几十行配置就能为接口加上生产级的多维流量保护 相关源码索引限流注解RateLimit.javaAOP 切面RateLimitAspect.javaLua 脚本rate_limit_single.lua单元测试RateLimitScriptTest.java【免费下载链接】interview-guide基于 Spring Boot 4.1、Java 25、Spring AI 2.0、React、PostgreSQL/pgvector、Redis 和 RustFS 构建的开源 AI 面试平台支持简历智能分析、模拟面试、语音面试和知识库 RAG。项目地址: https://gitcode.com/gh_mirrors/inter/interview-guide创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考