如何通过 Nginx 对 API 接口进行细粒度限流

Nginx细粒度限流需结合limit_req模块与自定义key，按用户、IP、App ID等维度精准控制速率；支持多zone分层策略、burst缓冲、429响应及空值预处理。

通过 Nginx 实现 API 接口的细粒度限流，核心在于结合 limit_req 模块与自定义 key，按用户、IP、App ID、Token 或请求路径等维度精准控制请求速率，避免“一刀切”式限流影响正常调用。

基于不同标识符构造限流 key

Nginx 的 limit_req_zone 指令支持从变量中提取唯一标识作为限流依据。关键是要选择业务语义明确、不易伪造且可稳定提取的字段：

• 按用户身份限流：使用请求头中的 X-User-ID 或解析 JWT 中的 sub 字段（需配合 ngx_http_auth_jwt_module 或 OpenResty 的 Lua 解析）
• 按 App ID 限流：提取客户端传入的 X-App-ID 请求头，适用于多租户或第三方接入场景
• 按 API 路径 + 用户组合限流：例如 $uri:$http_x_user_id，实现“每个用户对 /v1/orders 的独立配额”
• 按 Token 哈希限流：对 $http_authorization 做哈希（如 md5($http_authorization)），兼顾安全性与去重性

配置分层限流策略

单一限流 zone 往往不够灵活。可通过多个 limit_req_zone 定义不同粒度的配额，并在 location 中叠加使用：

• 全局 IP 级兜底限流（如 100r/s），防恶意扫描
• 用户级主限流（如 10r/s），保障核心业务公平性
• 高频接口专项限流（如 /search 单独设 5r/s），避免拖累其他路径
• 所有限流指令按顺序生效，Nginx 会取最严格的那个结果

处理突发流量与平滑响应

直接拒绝（limit_req 默认行为）易导致客户端重试风暴。建议启用缓冲和延迟机制：

• 用 burst=5 nodelay 允许短时突发，不排队直接处理
• 用 burst=20 delay=10 缓冲 20 个请求，超 10 个后开始排队，避免瞬时压垮后端
• 返回友好错误码：通过 limit_req_status 429 统一设为 429 Too Many Requests，并添加 Retry-After 响应头
• 记录限流日志：limit_req_log_level warn，便于监控异常触发点

验证与动态调整限流参数

上线前务必验证 key 提取逻辑与限流效果：

• 用 curl -H "X-User-ID: u123" http://api.example.com/v1/data 多次请求，观察响应状态与 Header 中的 X-RateLimit-Remaining（需配合 Lua 注入）
• 通过 nginx -t && nginx -s reload 热更新限流阈值，无需重启进程
• 将限流阈值外置为变量（如 set $rate_limit "5r/s";），方便通过配置中心动态下发
• 配合 Prometheus + nginx-vts-exporter 监控各 zone 的 rejected / passed 请求量，及时发现策略偏差

不复杂但容易忽略：限流 key 中若含空值（如未传 X-User-ID），会导致所有匿名请求打到同一个 bucket。务必用 map 指令预处理，把空值映射为特殊标记（如 "anonymous"），再参与 zone 计算。