Redux Toolkit Query 中自动刷新 Token 的实现与常见问题

理解 RTK Query 的认证流程

Redux Toolkit Query（RTK Query）是 Redux Toolkit 提供的一个强大的数据获取和缓存解决方案。在实际应用中，处理认证流程特别是 Token 刷新是一个常见需求。本文将详细介绍如何实现自动刷新 Token 的功能，并分析一个典型的问题场景。

核心实现方案

RTK Query 提供了扩展基础查询（baseQuery）的能力，允许我们在请求失败时（如 401 未授权错误）自动刷新访问令牌。关键实现步骤如下：

1. 创建互斥锁：使用 async-mutex 库确保同一时间只有一个刷新 Token 的请求
2. 扩展基础查询：包装原始的 fetchBaseQuery，添加自动刷新逻辑
3. 处理 401 错误：检测到未授权错误时尝试刷新 Token
4. 重试原始请求：获取新 Token 后重新发送原始请求

典型问题分析

在实现过程中，开发者可能会遇到一个常见问题：无法从注入的端点中解构出 React Hook。这通常是由于错误的导入路径导致的。

问题表现

当尝试从注入的 API 中解构出类似 useGetUserByIdQuery 这样的 React Hook 时，TypeScript 会报错提示该 Hook 不存在。错误信息会指出类型定义中缺少相应的 Hook。

根本原因

这个问题源于错误的导入路径。RTK Query 提供了两个入口点：

1. 核心功能入口：@reduxjs/toolkit/query
2. React 专用入口：@reduxjs/toolkit/query/react

只有从 React 专用入口导入时，才会自动生成 React Hook。如果从核心功能入口导入，虽然 API 能正常工作，但不会生成 React Hook。

解决方案

只需将导入语句从：

import {createApi, fetchBaseQuery} from '@reduxjs/toolkit/query';

修改为：

import {createApi, fetchBaseQuery} from '@reduxjs/toolkit/query/react';

完整实现示例

以下是结合自动刷新 Token 功能的完整实现示例：

import {createApi, fetchBaseQuery} from '@reduxjs/toolkit/query/react';
import type {BaseQueryFn, FetchArgs, FetchBaseQueryError} from '@reduxjs/toolkit/query';
import {Mutex} from 'async-mutex';

const mutex = new Mutex();

const baseQuery = fetchBaseQuery({baseUrl: '/'});

const baseQueryWithReauth: BaseQueryFn<
  string | FetchArgs,
  unknown,
  FetchBaseQueryError
> = async (args, api, extraOptions) => {
  await mutex.waitForUnlock();
  let result = await baseQuery(args, api, extraOptions);

  if (result.error?.status === 401) {
    if (!mutex.isLocked()) {
      const release = await mutex.acquire();
      try {
        const refreshResult = await baseQuery('/refreshToken', api, extraOptions);
        if (refreshResult.data) {
          result = await baseQuery(args, api, extraOptions);
        }
      } finally {
        release();
      }
    } else {
      await mutex.waitForUnlock();
      result = await baseQuery(args, api, extraOptions);
    }
  }
  return result;
};

export const baseApi = createApi({
  reducerPath: 'baseApi',
  baseQuery: baseQueryWithReauth,
  endpoints: () => ({}),
});

export const extendedApi = baseApi.injectEndpoints({
  endpoints: (builder) => ({
    getUserById: builder.query<any, {userId: string; accessToken: string}>({
      query: ({userId, accessToken}) => ({
        url: `user.get?ID=${userId}`,
        headers: {Authorization: `Bearer ${accessToken}`},
      }),
    }),
  }),
});

export const {useGetUserByIdQuery} = extendedApi;

最佳实践建议

1. 错误处理：在刷新 Token 失败时应添加适当的错误处理逻辑，如跳转到登录页
2. Token 存储：刷新成功后需要更新存储中的 Token，可以通过 dispatch action 实现
3. 性能考虑：避免频繁刷新 Token，可以在请求前检查 Token 是否即将过期
4. 类型安全：为查询参数和返回类型定义明确的接口，而不是使用 any

通过正确实现自动刷新 Token 功能，可以显著提升应用的用户体验，避免因 Token 过期导致的频繁重新登录问题。