能力：请求重试（Retry）

网络抖动、服务端瞬断时，自动重试失败请求，业务代码无需任何感知。

默认行为

• 默认 attempts: 3（首次 + 2 次重试），retry: true 开箱即重试
• 默认 delay: 300 + backoff: 'exponential'（指数退避：300ms → 600ms → ...），避免瞬时重试加重故障服务压力
• 默认排除 POST / PUT / PATCH / DELETE（写操作不自动重试）
• 只重试白名单内的 HTTP 状态码：408, 429, 500, 502, 503, 504
• 只重试白名单内的网络错误码：ECONNABORTED, ETIMEDOUT
• 304、ERR_CANCELED、AbortError、ABORT_ERR 和 Axios legacy cancel 绝不重试

单业务场景配置

// ============ 全局开启：GET 请求自动重试 ============
const requestManager = setupRequestGuard(axios, {
  defaults: {
    retry: {
      attempts: 3,            // 最多尝试 3 次（首次 + 2 次重试）
      delay: 200,             // 初始延迟 200ms
      backoff: 'exponential'  // 指数退避：200ms → 400ms → 800ms
    }
  }
});

// ============ 请求级覆盖：某个接口重试 5 次 ============
await axios.get('/api/config', {
  requestGuard: {
    retry: {
      attempts: 5,            // 这个接口比较重要，多试几次
      delay: 500,
      backoff: 'linear'       // 线性退避：500ms → 1000ms → 1500ms → 2000ms
    }
  }
});

// ============ POST 请求显式开启重试 ============
// 默认排除写操作，但请求级配置不受此限制
await axios.post('/api/idempotent-action', data, {
  requestGuard: {
    retry: {
      attempts: 2,           // 重试 1 次
      delay: 1000            // 等 1 秒再试
    }
  }
});

// ============ 自定义重试判断 ============
await axios.get('/api/data', {
  requestGuard: {
    retry: {
      attempts: 3,
      delay: 300,
      // canRetry 优先级最高，配置后不再走内部白名单逻辑
      canRetry({ error, attempt, status, code }) {
        return status === 503 || code === 'ECONNABORTED';
      }
    }
  }
});

配置项

配置项	类型	默认值	说明
enabled	boolean	true	能力开关
attempts	number	3	最大执行次数（1=不重试，2=重试 1 次，3=重试 2 次）
delay	number	300	初始延迟时间（ms）
backoff	string	'exponential'	退避算法：fixed / linear / exponential
methods	string[]	[]	允许重试的方法白名单（空=不限制）
excludeMethods	string[]	['POST','PUT','PATCH','DELETE']	排除重试的方法（请求级不受限制）
statusCodes	number[]	[408,429,500,502,503,504]	允许重试的 HTTP 状态码
errorCodes	string[]	['ECONNABORTED','ETIMEDOUT']	允许重试的网络错误码
canRetry	function | null	null	自定义判断函数，优先级最高

退避算法

算法	公式	示例（delay=200）
fixed	delay	200, 200, 200
linear	delay × attemptIndex	200, 400, 600
exponential	delay × 2^(attemptIndex-1)	200, 400, 800

429 + Retry-After

当服务端返回 429 状态码时，自动解析 Retry-After header 并覆盖配置的延迟时间：

// 服务端返回：429 Too Many Requests + Retry-After: 5
// guard 自动等待 5 秒后重试，无需业务处理

状态清理

场景	行为
clearState()	waiting 状态立即取消（抛 RequestGuardRetryCancelledError）；inFlight 让其自然完成但不再继续重试
uninstall()	同 clearState 语义，额外解绑定时器和事件监听
requestGuard: false	完全绕过守护层，不进入 retry 逻辑