Node.js 调用第三方 API 超时怎么配置 axios 请求拦截器统一处理异步重试

在 Node.js 服务中调用第三方 API 时，网络波动导致的超时不可避免。最稳妥的工程实践是通过 axios 拦截器结合 axios-retry 插件实现统一重试，但必须严格配置超时阈值和重试条件。

核心结论：拦截器自动重试能提升可用性，但必须限制重试次数并确认接口幂等性。

适用场景：GET 请求或具备幂等性的写操作
关键配置：必须设置 timeout 和最大重试次数（建议 3 次）
风险控制：非幂等接口（如支付）禁止自动重试

1. 安装依赖

除了 axios 核心库，推荐使用社区维护的 axios-retry 插件，它内部实现了拦截器逻辑，比手写更稳定。

npm install axios axios-retry

2. 配置 Axios 实例与重试策略

创建独立的 axios 实例，避免污染全局。重点配置 timeout 防止请求挂起，并通过 axiosRetry 设定重试规则。

const axios = require('axios');
const axiosRetry = require('axios-retry');

// 1. 创建实例
const client = axios.create({
  baseURL: 'https://api.third-party.com',
  timeout: 5000 // 关键：设置请求超时时间，默认无限制易导致进程挂起
});

// 2. 挂载重试插件
axiosRetry(client, {
  retries: 3, // 关键：最大重试次数，防止无限重试
  retryDelay: (retryCount) => {
    return retryCount * 1000; // 延迟策略：1s, 2s, 3s
  },
  retryCondition: (error) => {
    // 关键：仅对网络错误或 5xx 服务端错误重试
    // 默认策略会避开 POST/PUT 等非幂等请求，如需重试需自定义
    return axiosRetry.isNetworkOrIdempotentRequestError(error);
  },
  onRetry: (retryCount, error, requestConfig) => {
    console.warn(`Request failed, retrying ${retryCount} times...`);
  }
});

module.exports = client;

3. 验证重试是否生效

不要直接依赖生产环境验证，建议在本地模拟超时场景。

步骤：

使用 httpbin 等测试服务模拟延迟：https://httpbin.org/delay/6
将 baseURL 指向该地址，设置 timeout 为 2000ms
运行代码，观察控制台是否打印 3 次 onRetry 日志
检查最终是否抛出 ECONNABORTED 错误

4. 常见坑与排查

1. 非幂等接口重复提交

Node.js 调用第三方 API 超时怎么配置 axios 请求拦截器统一处理异步重试

POST/PUT 请求默认不会重试。如果业务允许重试，需在 retryCondition 中放行，但务必确保接口支持幂等（如携带唯一 request_id）。

2. 无限重试导致雪崩

务必设置 retries 上限。如果不设置，网络持续故障时会导致请求堆积，拖垮服务。

3. 超时时间设置不合理

timeout 应小于网关或负载均衡器的超时时间，否则上游已断开而 Node.js 仍在等待，造成资源浪费。