axios-retry源码解析：深入理解拦截器与重试机制实现原理

axios-retry源码解析：深入理解拦截器与重试机制实现原理

【免费下载链接】axios-retryAxios plugin that intercepts failed requests and retries them whenever possible项目地址: https://gitcode.com/gh_mirrors/ax/axios-retry

axios-retry是一个功能强大的Axios插件，它能够拦截失败的请求并在可能的情况下自动重试，有效提升网络请求的稳定性和可靠性。本文将深入剖析axios-retry的源码实现，帮助开发者理解其拦截器工作原理和重试机制设计。

核心功能与项目结构

axios-retry作为Axios生态中的重要补充，通过拦截器机制实现了请求失败后的智能重试。项目采用TypeScript开发，主要代码集中在src/index.ts文件中，测试用例则位于spec/index.spec.ts。

核心功能包括：

• 基于HTTP状态码和请求类型的智能重试判断
• 可配置的重试次数和重试延迟策略
• 支持指数退避和线性延迟两种重试间隔算法
• 请求级别的个性化重试配置
• 重试过程中的事件回调机制

拦截器实现原理

axios-retry的核心能力来源于Axios的拦截器机制。在src/index.ts中，通过注册请求拦截器和响应拦截器实现了重试逻辑的注入。

请求拦截器初始化

请求拦截器主要负责初始化重试状态，代码如下：

const requestInterceptorId = axiosInstance.interceptors.request.use((config) => { setCurrentState(config, defaultOptions, true); if (config[namespace]?.validateResponse) { config.validateStatus = () => false; } return config; });

setCurrentState函数会初始化重试配置，包括重试次数、上次请求时间等状态信息，并将这些信息存储在请求配置的axios-retry命名空间下。

响应拦截器实现重试逻辑

响应拦截器是重试机制的核心，代码位于src/index.ts的响应拦截器错误处理部分：

const responseInterceptorId = axiosInstance.interceptors.response.use(null, async (error) => { const { config } = error; if (!config) { return Promise.reject(error); } const currentState = setCurrentState(config, defaultOptions); if (error.response && currentState.validateResponse?.(error.response)) { return error.response; } if (await shouldRetry(currentState, error)) { return handleRetry(axiosInstance, currentState, error, config); } await handleMaxRetryTimesExceeded(currentState, error); return Promise.reject(error); });

响应拦截器的工作流程可以概括为：

1. 检查请求配置是否存在
2. 初始化或更新当前重试状态
3. 根据自定义响应验证逻辑判断是否直接返回
4. 判断是否满足重试条件
5. 满足条件则执行重试逻辑
6. 达到最大重试次数时执行回调并拒绝请求

重试条件判断机制

axios-retry的重试条件判断是其智能化的关键所在。默认情况下，它会重试网络错误或幂等请求的5xx错误。

默认重试条件

在DEFAULT_OPTIONS中定义了默认的重试条件：

export const DEFAULT_OPTIONS: Required<IAxiosRetryConfig> = { retries: 3, retryCondition: isNetworkOrIdempotentRequestError, retryDelay: noDelay, shouldResetTimeout: false, onRetry: () => {}, onMaxRetryTimesExceeded: () => {}, validateResponse: null };

isNetworkOrIdempotentRequestError函数结合了网络错误判断和幂等请求判断：

export function isNetworkOrIdempotentRequestError(error: AxiosError): boolean { return isNetworkError(error) || isIdempotentRequestError(error); }

幂等请求判断

幂等请求判断确保只有安全的请求才会被重试，避免重复提交导致的副作用：

const IDEMPOTENT_HTTP_METHODS = ['get', 'head', 'options', 'put', 'delete']; export function isIdempotentRequestError(error: AxiosError): boolean { if (!error.config?.method) { return false; } return isRetryableError(error) && IDEMPOTENT_HTTP_METHODS.indexOf(error.config.method) !== -1; }

可重试错误判断

isRetryableError函数定义了哪些状态码的错误应该被重试：

export function isRetryableError(error: AxiosError): boolean { return ( error.code !== 'ECONNABORTED' && (!error.response || error.response.status === 429 || (error.response.status >= 500 && error.response.status <= 599)) ); }

默认情况下，429(Too Many Requests)和5xx系列错误会触发重试，而ECONNABORTED(超时)错误不会被重试。

重试延迟策略

axios-retry提供了灵活的重试延迟策略，包括默认无延迟、指数退避和线性延迟。

指数退避延迟

指数退避策略会随着重试次数增加而指数级增加延迟时间，有效避免了请求风暴：

export function exponentialDelay( retryCount = 0, error: AxiosError | undefined = undefined, delayFactor = 100 ): number { const calculatedDelay = 2 ** retryCount * delayFactor; const delay = Math.max(calculatedDelay, retryAfter(error)); const randomSum = delay * 0.2 * Math.random(); // 0-20%的随机延迟 return delay + randomSum; }

线性延迟

线性延迟策略则是每次重试都增加固定的延迟时间：

export function linearDelay( delayFactor: number | undefined = 100 ): (retryCount: number, error: AxiosError | undefined) => number { return (retryCount = 0, error = undefined) => { const delay = retryCount * delayFactor; return Math.max(delay, retryAfter(error)); }; }

尊重Retry-After响应头

retryAfter函数会解析响应头中的Retry-After字段，优先使用服务器建议的重试时间：

export function retryAfter(error: AxiosError | undefined = undefined): number { const retryAfterHeader = error?.response?.headers['retry-after']; if (!retryAfterHeader) { return 0; } let retryAfterMs = (Number(retryAfterHeader) || 0) * 1000; if (retryAfterMs === 0) { retryAfterMs = (new Date(retryAfterHeader).valueOf() || 0) - Date.now(); } return Math.max(0, retryAfterMs); }

重试执行流程

handleRetry函数是执行重试的核心逻辑，位于src/index.ts中：

async function handleRetry( axiosInstance: AxiosInstance, currentState: Required<IAxiosRetryConfigExtended>, error: AxiosError, config: AxiosRequestConfig ) { currentState.retryCount += 1; const { retryDelay, shouldResetTimeout, onRetry } = currentState; const delay = retryDelay(currentState.retryCount, error); fixConfig(axiosInstance, config); if (!shouldResetTimeout && config.timeout && currentState.lastRequestTime) { const lastRequestDuration = Date.now() - currentState.lastRequestTime; const timeout = config.timeout - lastRequestDuration - delay; if (timeout <= 0) { return Promise.reject(error); } config.timeout = timeout; } config.transformRequest = [(data) => data]; await onRetry(currentState.retryCount, error, config); if (config.signal?.aborted) { return Promise.resolve(axiosInstance(config)); } return new Promise((resolve) => { const abortListener = () => { clearTimeout(timeout); resolve(axiosInstance(config)); }; const timeout = setTimeout(() => { resolve(axiosInstance(config)); if (config.signal?.removeEventListener) { config.signal.removeEventListener('abort', abortListener); } }, delay); if (config.signal?.addEventListener) { config.signal.addEventListener('abort', abortListener, { once: true }); } }); }

这段代码处理了重试过程中的关键步骤：

1. 增加重试计数
2. 计算重试延迟时间
3. 修复配置中的循环引用问题
4. 调整超时时间（如果不重置超时）
5. 执行重试前的回调函数
6. 处理AbortSignal中断
7. 延迟后重新发起请求

配置合并与优先级

axios-retry支持多级配置，包括全局默认配置和请求级别的个性化配置。配置合并逻辑在getRequestOptions函数中实现：

function getRequestOptions( config: AxiosRequestConfig, defaultOptions: IAxiosRetryConfig ): Required<IAxiosRetryConfig> & IAxiosRetryConfigExtended { return { ...DEFAULT_OPTIONS, ...defaultOptions, ...config[namespace] }; }

配置的优先级从高到低为：请求级别配置 > 实例级别配置 > 默认配置。

事件回调机制

axios-retry提供了丰富的事件回调，允许开发者在重试过程中执行自定义逻辑：

• onRetry: 每次重试前触发
• onMaxRetryTimesExceeded: 达到最大重试次数后触发

这些回调可以是同步函数，也可以是返回Promise的异步函数，为复杂场景提供了灵活性。

测试用例分析

spec/index.spec.ts包含了全面的测试用例，覆盖了各种重试场景：

• 成功响应处理
• 错误响应重试判断
• 不同HTTP方法的重试策略
• 超时处理与重置
• 自定义重试条件
• 各种延迟策略测试
• 事件回调测试

测试使用Jasmine框架和nock库模拟HTTP请求，确保了代码的可靠性和稳定性。

总结与最佳实践

axios-retry通过优雅的拦截器设计和灵活的配置选项，为Axios请求提供了强大的重试机制。在使用过程中，建议：

1. 根据业务需求合理设置重试次数，避免过多重试导致的性能问题
2. 对非幂等请求（如POST）谨慎使用重试，避免产生副作用
3. 使用指数退避策略减轻服务器压力
4. 结合onRetry回调实现重试日志记录
5. 利用validateResponse自定义响应验证逻辑

通过深入理解axios-retry的实现原理，开发者可以更好地配置和扩展重试策略，提升应用的稳定性和用户体验。

要开始使用axios-retry，首先需要克隆仓库：

git clone https://gitcode.com/gh_mirrors/ax/axios-retry

然后根据项目需求进行配置和使用，详细的使用方法可以参考项目文档和测试用例。

axios-retry的源码设计简洁而强大，充分利用了Axios的拦截器机制，为我们展示了如何优雅地扩展Axios功能。无论是学习拦截器实现，还是理解重试策略设计，axios-retry都是一个值得深入研究的优秀开源项目。

【免费下载链接】axios-retryAxios plugin that intercepts failed requests and retries them whenever possible项目地址: https://gitcode.com/gh_mirrors/ax/axios-retry