Nginx 中如何针对 API 服务接入实施频率限制

Nginx API限流需围绕“谁调用、调什么、怎么控”三层构建：必须在http块顶层定义limit_req_zone，key应优先取X-Api-Key或JWT解析的用户标识而非IP，用map动态绑定路径（如仅限/api/v1/pay），配合burst和nodelay控制突发策略，并统一返回429状态码及JSON响应。

在 Nginx 中对 API 服务接入实施频率限制，关键不是简单加个限流指令，而是围绕“谁调用”“调什么”“怎么控”三层逻辑构建可落地的策略。单靠 limit_req 指令本身不会生效，必须配合顶层 limit_req_zone 定义、合理 key 选取、以及与 proxy_pass 的执行顺序协同。

按真实调用者身份限流，而非仅靠 IP

直接用 $remote_addr 或 $binary_remote_addr 限流容易误伤（如企业出口 NAT、CDN 回源），也不符合业务分级需求。应优先提取请求头中的可信标识：

• 若 API 使用 X-Api-Key：在 http 块中定义 limit_req_zone $http_x_api_key zone=api_perkey:10m rate=20r/s;
• 若使用 JWT，在 location 中通过 Lua 解析 token 并提取 sub 或 client_id，再 set 到变量供限流使用
• 如需兜底，可叠加一层宽松的 IP 限流（如 rate=100r/m），但 zone 名要独立，避免干扰主策略

让限流精准作用于特定 API 路径

限流不能全局一刀切，必须绑定到具体路径。常见错误是把 limit_req 直接写在 location 里却不配 zone——这会导致规则完全不生效。

• limit_req_zone 必须定义在 http 块顶层，不能嵌套在 server 或 location 内
• 用 map 指令动态控制是否启用限流：例如只对 /api/v1/pay 生效，而放过 /healthz、/metrics
• 示例：map $uri $limit_key { ~^/api/v1/pay $http_x_api_key; default ""; }，再基于 $limit_key 定义 zone

配置 burst 和 nodelay 以匹配业务敏感度

这两个参数决定超限请求是排队还是立即拒绝，直接影响用户体验和后端压力：

• burst=5 nodelay：允许短时脉冲（如用户连点两次提交），适合支付类接口
• burst=0 或省略 burst：严格按 rate 放行，适合库存扣减、短信发送等强一致性场景
• 不加 nodelay 时，burst 是排队缓冲区；加了则变成“瞬时弹性容量”，超出部分立刻返回 429

返回友好且可追踪的限流响应

默认返回 503 对 API 不友好，也难被前端统一处理：

• 用 limit_req_status 429 显式设为标准码
• 搭配 error_page 429 = @rate_limited 返回 JSON：{"error":"rate_limit_exceeded","retry_after":60}
• 开启 limit_req_log_level warn，便于从日志中分析高频调用来源或异常模式