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 计算。
