本教程详细阐述了如何利用 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 状态码时，它能够识别出这是由于访问令牌过期导致的，并尝试刷新令牌。
核心原理
- 错误捕获： 应用程序通过 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 中，以防止客户端 JavaScript 访问和 XSS 攻击。
-
并发请求处理： 当多个 API 请求几乎同时因令牌过期而失败时，可能会导致多个刷新令牌请求被发送。这可能造成竞态条件或不必要的服务器负载。一个健壮的解决方案是实现一个“锁”机制：
- 当第一个 403 错误触发刷新时，设置一个全局标志（例如 isRefreshing = true）。
- 后续所有因 403 失败的请求都应该暂停，并订阅一个 Promise，等待令牌刷新完成。
- 令牌刷新完成后，解决该 Promise，并用新的令牌重试所有等待的请求。
- 刷新失败时，拒绝所有等待的请求。
- 刷新令牌过期： 即使是刷新令牌也有其生命周期。当刷新令牌也过期或无效时，自动化刷新机制将无法工作。此时，应用程序必须清除所有本地存储的认证信息，并强制用户重定向到登录页面进行完全重新认证。
- 用户体验： 在令牌刷新过程中，用户可能会遇到短暂的延迟。可以考虑在 UI 上显示一个加载指示器，以提供更好的用户反馈。
- 错误处理： 除了 403 之外，其他类型的错误（如网络错误、服务器错误）也需要妥善处理。拦截器可以作为统一错误处理的入口。
- 更健壮的检查： 在某些高级场景中，可以在触发刷新之前增加一个额外的安全检查：验证原始请求的 Authorization 头中的访问令牌是否与当前客户端存储的访问令牌一致。这可以防止在令牌被盗用后，攻击者使用旧的访问令牌来触发刷新。
- 分离关注点： 建议将令牌存储、刷新逻辑封装在独立的认证服务模块中，使拦截器保持简洁，只负责调用和处理刷新结果。
总结
通过巧妙地利用 Axios 响应拦截器，我们可以构建一个强大而灵活的自动化访问令牌刷新机制。这不仅能够显著提升用户体验，避免因令牌过期而频繁重新登录的困扰，还能在不牺牲安全性的前提下，简化客户端的认证管理。正确实现和维护这一机制，对于构建健壮且用户友好的现代 Web 应用程序至关重要。
