自动化刷新访问令牌：使用 Axios 拦截器处理身份验证过期

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

自动化刷新访问令牌：使用 Axios 拦截器处理身份验证过期

2025-10-15

浏览次数：次

返回列表

自动化刷新访问令牌：使用 Axios 拦截器处理身份验证过期

本教程详细阐述了如何利用 axios 拦截器自动处理短期访问令牌的过期问题。通过配置响应拦截器，我们可以在接收到 403 unauthorized 错误时，自动触发令牌刷新机制，更新访问令牌并重试失败的请求，从而无缝地维持用户会话，提升用户体验。

引言：理解访问令牌的挑战

在现代 Web 应用程序中，为了保障 API 访问的安全性，通常会采用基于令牌的身份验证机制。其中，访问令牌（Access Token）扮演着关键角色，它代表了用户或客户端的授权凭证。然而，出于安全考虑，访问令牌通常具有较短的生命周期（例如，一小时）。这意味着，在用户活跃期间，访问令牌可能会频繁过期，导致用户的 API 请求因缺乏有效凭证而失败，从而影响用户体验，迫使他们重新登录。

为了解决这一问题，引入了自动化令牌刷新机制。其核心思想是，当访问令牌过期时，系统能够静默地使用一个生命周期更长的刷新令牌（Refresh Token）去认证服务器获取新的访问令牌，并在不打断用户操作的情况下，用新的令牌重试之前的失败请求。

Axios 拦截器：自动刷新机制的核心

Axios 是一个流行的基于 Promise 的 HTTP 客户端，广泛用于浏览器和 Node.js 环境。它提供了一个强大的功能——拦截器（Interceptors），允许我们在请求发送前或响应返回后进行自定义处理。利用 Axios 拦截器，我们可以优雅地实现访问令牌的自动化刷新逻辑。

拦截器分为两种：

请求拦截器 (Request Interceptors)： 在请求发送到服务器之前对其进行处理，例如添加身份验证头。
响应拦截器 (Response Interceptors)： 在响应被 then 或 catch 处理之前对其进行处理，例如统一处理错误或刷新令牌。

在本场景中，我们将主要利用响应拦截器来捕获因访问令牌过期导致的错误，并触发刷新流程。

构建访问令牌刷新拦截器

自动化令牌刷新的核心在于，当应用程序收到一个 403 Unauthorized（或 401 Unauthorized，具体取决于后端实现）的 HTTP 状态码时，它能够识别出这是由于访问令牌过期导致的，并尝试刷新令牌。

察言观数AskTable

企业级AI数据表格智能体平台

78 查看详情察言观数AskTable

核心原理

错误捕获： 应用程序通过 Axios 响应拦截器捕获所有 HTTP 响应。
状态码判断： 如果响应状态码是 403 Unauthorized 且请求尚未被重试过，则认为访问令牌可能已过期。
令牌刷新： 调用一个专门的函数来使用刷新令牌获取新的访问令牌。
更新凭证： 将新的访问令牌更新到 Axios 的默认请求头中。
重试请求： 使用新的访问令牌重新发送之前失败的请求。

实现步骤与代码示例

以下是使用 Axios 拦截器实现自动刷新访问令牌的代码示例：

import axios from 'axios';

// 创建一个 Axios 实例，方便管理和配置
const axiosApiInstance = axios.create();

// 假设我们有一个函数来获取和刷新访问令牌
// 这个函数需要您根据实际的认证服务实现
async function refreshAccessToken() {
  try {
    // 实际场景中，这里会使用 refresh token 向认证服务器发起请求
    // 例如：const response = await axios.post('/auth/refresh-token', { refreshToken: getStoredRefreshToken() });
    // return response.data.newAccessToken;

    // 模拟异步获取新令牌
    console.log("尝试刷新访问令牌...");
    const newAccessToken = await new Promise(resolve => setTimeout(() => {
      const token = 'new_access_token_' + Date.now();
      console.log("获取到新令牌:", token);
      resolve(token);
    }, 1000));
    return newAccessToken;
  } catch (error) {
    console.error("刷新令牌失败:", error);
    // 刷新令牌失败，通常意味着刷新令牌也已过期或无效
    // 此时应清除所有令牌，并引导用户重新登录
    // 例如：clearAuthTokens(); window.location.href = '/login';
    throw error; // 抛出错误，让后续的 catch 块处理
  }
}

// 响应拦截器配置
axiosApiInstance.interceptors.response.use(
  (response) => {
    // 如果响应没有错误，直接返回
    return response;
  },
  async function (error) {
    const originalRequest = error.config;

    // 检查是否是 403 Unauthorized 错误，并且该请求尚未被重试过
    if (error.response && error.response.status === 403 && !originalRequest._retry) {
      originalRequest._retry = true; // 设置重试标志，防止无限循环

      try {
        // 调用刷新令牌函数获取新的访问令牌
        const access_token = await refreshAccessToken();

        // 更新 Axios 默认请求头中的 Authorization 字段
        // 这样后续的所有请求都会使用新的访问令牌
        axiosApiInstance.defaults.headers.common['Authorization'] = 'Bearer ' + access_token;

        // 更新原始请求的 Authorization 头，以便重试时使用新令牌
        originalRequest.headers['Authorization'] = 'Bearer ' + access_token;

        // 使用新的令牌重新发送原始请求
        return axiosApiInstance(originalRequest);
      } catch (refreshError) {
        // 刷新令牌本身失败，可能是刷新令牌已过期
        console.error("刷新令牌后重试失败，引导用户重新登录", refreshError);
        // 这里可以执行清除用户会话、重定向到登录页等操作
        // 例如：window.location.href = '/login';
        return Promise.reject(refreshError); // 抛出错误
      }
    }

    // 如果不是 403 错误，或者已经重试过，或者刷新令牌本身失败，则直接拒绝 Promise
    return Promise.reject(error);
  }
);

// 示例用法
async function fetchData() {
  try {
    const response = await axiosApiInstance.get('/api/protected-data');
    console.log("数据获取成功:", response.data);
  } catch (error) {
    console.error("数据获取失败:", error.message);
  }
}

// 假设初始访问令牌已设置
axiosApiInstance.defaults.headers.common['Authorization'] = 'Bearer initial_access_token';

// 模拟一个需要刷新的请求
// fetchData();

代码解释：

axiosApiInstance = axios.create(): 创建一个 Axios 实例，以便我们可以独立配置其拦截器，而不影响全局 axios 配置。
refreshAccessToken(): 这是一个占位函数，代表您实际的令牌刷新逻辑。它应该使用存储的刷新令牌向认证服务器发起请求，获取新的访问令牌，并在成功时返回它。如果刷新失败（例如，刷新令牌也过期），它应该抛出错误。
axiosApiInstance.interceptors.response.use(...): 配置响应拦截器。它接收两个回调函数：一个用于处理成功的响应，一个用于处理错误的响应。
error.response.status === 403 && !originalRequest._retry: 这是触发刷新逻辑的关键条件。
- error.response.status === 403：检查是否是未经授权的错误。
- !originalRequest._retry：这是一个自定义标志，用于确保令牌刷新和重试逻辑只执行一次，防止因刷新失败而导致的无限循环。当请求被重试时，我们会将此标志设置为 true。
await refreshAccessToken(): 调用我们定义的刷新函数来获取新的访问令牌。
axiosApiInstance.defaults.headers.common['Authorization'] = 'Bearer ' + access_token;: 更新 Axios 实例的默认 Authorization 头。这样，在此之后发出的所有新请求都会自动带上新的有效访问令牌。
originalRequest.headers['Authorization'] = 'Bearer ' + access_token;: 更新原始失败请求的 Authorization 头。这是为了确保当 axiosApiInstance(originalRequest) 被调用时，它会使用新的令牌发送。
return axiosApiInstance(originalRequest);: 使用新的访问令牌重新发送原始请求。如果重试成功，这个 Promise 将会解决，就像原始请求从未失败一样。
错误处理： 如果 refreshAccessToken 函数抛出错误（例如，刷新令牌也已过期），则拦截器会捕获这个错误，并将其通过 Promise.reject(refreshError) 向上抛出，以便应用程序可以处理最终的登录失败情况（例如，重定向到登录页）。

refreshAccessToken 函数的实现要点

refreshAccessToken 函数是整个自动刷新机制中与认证后端交互的核心。其实现需要考虑以下几点：

刷新令牌的存储： 刷新令牌通常比访问令牌寿命长，因此需要持久化存储。常见的存储方式包括：
- HTTP-only Cookies： 推荐方式，可有效防止 XSS 攻击窃取令牌。
- localStorage/sessionStorage： 易于访问，但容易受到 XSS 攻击。如果使用，需配合其他安全措施。
向认证服务器请求： 此函数应向认证服务器的特定刷新令牌端点发送请求，通常会携带刷新令牌作为凭证。
成功响应处理： 认证服务器成功响应后，会返回新的访问令牌（可能也包括新的刷新令牌）。此函数应返回新的访问令牌，并更新存储的刷新令牌（如果刷新令牌也更新了）。
失败响应处理： 如果刷新令牌本身已过期或无效，认证服务器会返回错误。此时，refreshAccessToken 函数应抛出错误，通知拦截器刷新失败，进而触发用户重新登录流程。

注意事项与进阶考量

刷新令牌的安全性： 刷新令牌是获取新访问令牌的关键，其安全性至关重要。应将其存储在 httpOnly 的 Secure Cookie 中，以防止客户端 J*aScript 访问和 XSS 攻击。
并发请求处理： 当多个 API 请求几乎同时因令牌过期而失败时，可能会导致多个刷新令牌请求被发送。这可能造成竞态条件或不必要的服务器负载。一个健壮的解决方案是实现一个“锁”机制：
- 当第一个 403 错误触发刷新时，设置一个全局标志（例如 isRefreshing = true）。
- 后续所有因 403 失败的请求都应该暂停，并订阅一个 Promise，等待令牌刷新完成。
- 令牌刷新完成后，解决该 Promise，并用新的令牌重试所有等待的请求。
- 刷新失败时，拒绝所有等待的请求。
刷新令牌过期： 即使是刷新令牌也有其生命周期。当刷新令牌也过期或无效时，自动化刷新机制将无法工作。此时，应用程序必须清除所有本地存储的认证信息，并强制用户重定向到登录页面进行完全重新认证。
用户体验： 在令牌刷新过程中，用户可能会遇到短暂的延迟。可以考虑在 UI 上显示一个加载指示器，以提供更好的用户反馈。
错误处理： 除了 403 之外，其他类型的错误（如网络错误、服务器错误）也需要妥善处理。拦截器可以作为统一错误处理的入口。
更健壮的检查： 在某些高级场景中，可以在触发刷新之前增加一个额外的安全检查：验证原始请求的 Authorization 头中的访问令牌是否与当前客户端存储的访问令牌一致。这可以防止在令牌被盗用后，攻击者使用旧的访问令牌来触发刷新。
分离关注点： 建议将令牌存储、刷新逻辑封装在独立的认证服务模块中，使拦截器保持简洁，只负责调用和处理刷新结果。