如何通过 limit_req_status 自定义触发限流时的响应格式以适配前端拦截逻辑-Nginx-PHP中文网

应将限流状态码设为429并自定义JSON响应体，通过limit_req_status设状态码、error_page跳转至named location，用return返回含code/message/retry_after字段的JSON，避免遗漏等号或proxy_pass。

如何通过 limit_req_status 自定义触发限流时的响应格式以适配前端拦截逻辑

可以通过 limit_req_status 指令配合 error_page 和自定义响应体，实现对限流触发时 HTTP 状态码和响应内容的完全控制，从而让前端能统一识别、解析并拦截限流响应。

明确限流状态码并绑定自定义响应

Nginx 默认在限流触发时返回 503，但该状态码语义宽泛（服务不可用），不利于前端精准判断是否为“被限流”。建议显式设置为更语义化的状态码，例如 429（Too Many Requests）：

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
server {
    location /api/ {
        limit_req zone=api burst=5 nodelay;
        limit_req_status 429;  # 关键：覆盖默认 503
        error_page 429 = @rate_limited;
    }
<pre class="brush:php;toolbar:false;">location @rate_limited {
    add_header Content-Type "application/json; charset=utf-8";
    return 429 '{"code":429,"message":"请求过于频繁，请稍后重试","retry_after":60}';
}

}

根据ui图生成前端页面

将一个或多个 UI 原型图、线框图、产品截图或设计稿转换为标准化、可直接交付的 PRD 风格文档，供产品、设计、前端和测试共同使用。适用于 Codex 需要分析 PC 网页、桌面端、移动端、响应式页面、独立弹窗、表单、表格、看板、数据大屏或多页面流程截图，还原页面结构与交互，强制套用固定文档模板，抽取跨页面共享规则，或把一组原型沉淀为单页规范文档加整体业务流程文档的场景。不适用于纯视觉审美点评、代码实现、接口设计、埋点方案、竞品分析或无 UI 输入的业务需求创作。

下载

确保响应体结构与前端拦截逻辑对齐

前端通常通过 Axios、Fetch 等库全局拦截错误响应。为便于统一处理，响应体应满足以下要求：

固定字段：如 code（数值型错误码）、message（用户提示）、retry_after（可选，单位秒，用于指导重试时机）
无 HTML 或纯文本：避免前端 JSON.parse 失败；Nginx 的 return 指令需显式指定 Content-Type
支持国际化占位（可选）：若需多语言，可由后端动态生成响应体，或通过 Nginx 变量注入简单上下文（如 $limit_req_status）

避免常见配置陷阱

不要遗漏 = 符号：写成 error_page 429 @rate_limited;（无等号）会导致重定向而非内部跳转，状态码仍为 302，破坏前端拦截逻辑
不要在 @rate_limited 中使用 proxy_pass：这会引入额外延迟和失败风险；限流响应必须轻量、本地生成
注意变量作用域：$binary_remote_addr 等变量在 @named_location 中不可用；如需携带客户端信息（如 IP），需提前用 map 提取到全局变量中

前端拦截示例（以 Axios 为例）

利用响应拦截器识别 429 并触发统一提示或退避策略：

axios.interceptors.response.use(
  res => res,
  error => {
    if (error.response?.status === 429) {
      const data = error.response.data;
      message.warning(data.message || '操作太频繁了');
      // 可选：自动延时重试
      if (data.retry_after) {
        setTimeout(() => { /* 重试逻辑 */ }, data.retry_after * 1000);
      }
      return Promise.reject(error);
    }
    return Promise.reject(error);
  }
);

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索前端的入门与实战技巧！