包版本包大小包下载量包类型定义

axios-auth-refresh

这个库通过axios的拦截器帮助你实现自动刷新授权。你可以在原始请求失败时轻松拦截它，刷新授权并继续原始请求，无需任何用户交互。

当请求由于授权失败时会发生什么完全由你决定。你可以运行刷新调用以获取新的授权令牌，或者运行自定义逻辑。

该插件会暂停等待新授权令牌期间收到的额外请求，并在新令牌可用时解决它们。

安装

npm install axios-auth-refresh --save
# 或
yarn add axios-auth-refresh

语法

createAuthRefreshInterceptor(
    axios: AxiosInstance,
    refreshAuthLogic: (failedRequest: any) => Promise<any>,
    options: AxiosAuthRefreshOptions = {}
): number;

参数

axios - Axios的一个实例
refreshAuthLogic - 用于刷新授权的函数（必须返回一个promise）。接受一个参数，即原始调用返回的failedRequest。
options - 拦截器的设置对象（参见可用选项）

返回值

拦截器的id，以便你可以手动拒绝它。

使用方法

要激活拦截器，你需要从axios-auth-refresh导入一个_默认导出_的函数，并用你想要拦截的axios实例以及刷新授权函数（你需要在其中编写刷新授权的逻辑）来调用它。

然后，拦截器将绑定到axios实例上，每当服务器返回401（未授权）状态码时（或者你在选项中提供的任何其他状态码），指定的逻辑就会运行。在refreshAuthLogic处理期间创建的所有新请求将绑定到refreshAuthLogic函数返回的Promise上。这意味着当获取到新的访问令牌或刷新逻辑失败时，这些请求将被解决。

import axios from 'axios';
import createAuthRefreshInterceptor from 'axios-auth-refresh';

// 将被调用以刷新授权的函数
const refreshAuthLogic = (failedRequest) =>
    axios.post('https://www.example.com/auth/token/refresh').then((tokenRefreshResponse) => {
        localStorage.setItem('token', tokenRefreshResponse.data.token);
        failedRequest.response.config.headers['Authorization'] = 'Bearer ' + tokenRefreshResponse.data.token;
        return Promise.resolve();
    });

// 实例化拦截器
createAuthRefreshInterceptor(axios, refreshAuthLogic);

// 发起调用。如果返回401错误，将运行refreshAuthLogic，
// 并使用新令牌重试请求
axios.get('https://www.example.com/restricted/area').then(/* ... */).catch(/* ... */);

跳过拦截器

:warning: 由于axios#2295错误，不支持v0.19.0版本。:warning:

:white_check_mark: 这个问题已在axios v0.19.1中修复

有可能跳过特定调用的拦截器逻辑。要做到这一点，你需要为每个不想拦截的请求在请求配置中传递skipAuthRefresh选项。

axios.get('https://www.example.com/', { skipAuthRefresh: true });

如果你使用TypeScript，你可以从axios-auth-refresh导入自定义请求配置接口。

import { AxiosAuthRefreshRequestConfig } from 'axios-auth-refresh';

请求拦截器

由于这个插件在刷新令牌时自动暂停额外的请求，最好将你的请求逻辑包装在一个函数中，以确保暂停的请求使用新获取的数据（如令牌）。

发送令牌的示例：

// 每次调用函数时获取新的令牌
function getAccessToken() {
    return localStorage.getItem('token');
}

// 使用拦截器将令牌注入请求
axios.interceptors.request.use((request) => {
    request.headers['Authorization'] = `Bearer ${getAccessToken()}`;
    return request;
});

可用选项

要拦截的状态码

你可以指定多个你想要拦截器运行的状态码。

{
    statusCodes: [401, 403], // 默认值：[ 401 ]
}

自定义拦截逻辑

你可以指定多个你想要拦截器运行的状态码。

{
    shouldRefresh: (error) =>
        error?.response?.data?.business_error_code === 100385,
}

暂停请求的重试实例

你可以指定用于重试暂停请求的实例。默认值为undefined，使用传递给createAuthRefreshInterceptor函数的实例。

{
    retryInstance: someAxiosInstance, // 默认值：undefined
}

发送暂停请求前的`onRetry`回调

你可以指定onRetry回调，它将在每个暂停请求被调用之前执行，并带有请求配置对象。

{
    onRetry: (requestConfig) => ({ ...requestConfig, baseURL: '' }), // 默认值：undefined
}

在"刷新逻辑"运行时暂停实例

当你的刷新逻辑正在运行时，拦截器将触发每个返回指定的options.statusCodes之一的请求（默认为HTTP 401）。

为了防止拦截器循环（当你的刷新逻辑失败并返回options.statusCodes中指定的任何状态码时），你需要在refreshAuthLogic函数内的刷新调用中使用skipAuthRefresh标志。

如果你的刷新逻辑不进行任何调用，你应该考虑在初始化拦截器时使用以下标志来在刷新挂起时暂停整个axios实例。这可以防止拦截器为每个失败的请求运行。

{
    pauseInstanceWhileRefreshing: true, // 默认值：false
}

拦截网络错误

某些CORS API在返回HTTP 401未授权响应时可能不会返回CORS响应头。在这种情况下，浏览器将无法读取响应头以确定响应状态码。

要拦截_任何_网络错误，启用interceptNetworkError选项。

注意：这应该作为最后的手段使用。如果这是用来解决不支持CORS的HTTP 401响应的API问题，你的重试逻辑可以尝试刷新认证来测试网络连接。

{
    interceptNetworkError: true, // 默认值：undefined
}

该库的其他用途

这个库还被用于：

由@amcsi实现的自动请求限流
由@LeoniePhiline实现的Google2FA的OTP挑战

你还有其他用途吗？创建一个PR来分享你的用例。

更新日志

v3.1.0
- 支持axios v0.21.1
- 引入interceptNetworkError选项。参见#133。
v3.0.0
- 由于名称不明确，skipWhileRefresh标志已被弃用，其逻辑已移至pauseInstanceWhileRefreshing标志
- pauseInstanceWhileRefreshing默认设置为false