@tanstack/react-query：React 服务器状态管理与数据同步解决方案
1 概述
@tanstack/react-query 是一个功能强大的异步状态管理库，专为简化 React 应用中的服务器状态管理而设计。它提供了一套全面的工具集，用于处理数据获取、缓存、同步和更新服务器状态，使开发者能够专注于业务逻辑而非数据获取细节。
作为现代前端开发的关键工具，@tanstack/react-query 解决了传统数据获取方案中的诸多痛点：
- 自动缓存与失效管理，减少不必要的网络请求
- 智能重试与背景刷新机制，提升用户体验
- 简洁的 API 设计，降低异步数据处理的复杂性
- 深度整合 TypeScript，提供完善的类型安全保障
- 与 React 生态无缝集成，支持 Suspense 等现代特性
最新版本 v5.84.2 带来了多项重要改进，包括统一的参数对象化 API、增强的类型推断能力、优化的缓存策略以及对 React 18 特性的更好支持。这些更新进一步提升了库的易用性和性能，使其成为构建高性能 React 应用的理想选择。
无论是小型项目还是大型企业级应用，@tanstack/react-query 都能显著简化数据管理流程，减少样板代码，并提供一致且可预测的状态管理体验。
2 安装与配置
2.1 环境要求
@tanstack/react-query v5 需要以下环境支持：
- React: 18.0.0 或更高版本
- TypeScript: 4.7 或更高版本（可选）
- Node.js: 16.0.0 或更高版本
2.2 安装命令
使用 npm
# 安装核心库
npm install @tanstack/react-query
# 安装开发工具（可选，用于调试）
npm install --save-dev @tanstack/react-query-devtools
# 如果使用 TypeScript，确保安装类型定义
npm install --save-dev @types/react @types/react-dom
使用 yarn
# 安装核心库
yarn add @tanstack/react-query
# 安装开发工具
yarn add -D @tanstack/react-query-devtools
使用 pnpm
# 安装核心库
pnpm add @tanstack/react-query
# 安装开发工具
pnpm add -D @tanstack/react-query-devtools
安装指定版本
如需安装特定版本（如本文介绍的 v5.84.2）：
npm install @tanstack/react-query@5.84.2
npm install --save-dev @tanstack/react-query-devtools@5.84.2
2.3 项目初始化
创建新项目（可选）
如果您正在创建新的 React 项目，推荐使用以下方式：
# 使用 Create React App
npx create-react-app my-app --template typescript
cd my-app
# 或使用 Vite（推荐，更快的开发体验）
npm create vite@latest my-app -- --template react-ts
cd my-app
npm install
# 安装 React Query
npm install @tanstack/react-query @tanstack/react-query-devtools
2.4 基本配置
步骤 1：创建 QueryClient
在 src/lib/queryClient.ts 文件中创建 QueryClient 实例：
// src/lib/queryClient.ts
import { QueryClient } from '@tanstack/react-query'
export const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 60 * 1000, // 数据保鲜时间：1分钟
gcTime: 10 * 60 * 1000, // 垃圾回收时间：10分钟
retry: 1, // 失败重试次数
refetchOnWindowFocus: true, // 窗口聚焦时重新获取
refetchOnReconnect: true, // 网络重连时重新获取
},
mutations: {
retry: 1, // 变更操作重试次数
},
},
})
步骤 2：配置应用入口
在 src/main.tsx（Vite）或 src/index.tsx（CRA）中配置 Provider：
// src/main.tsx (Vite) 或 src/index.tsx (CRA)
import React from 'react'
import ReactDOM from 'react-dom/client'
import { QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { queryClient } from './lib/queryClient'
import App from './App'
import './index.css'
ReactDOM.createRoot(document.getElementById('root')!).render(
{/* 仅在开发环境显示开发工具 */}
{process.env.NODE_ENV === 'development' && (
)
步骤 3：配置详细选项
如需更精细的控制，可以扩展 QueryClient 配置：
// src/lib/queryClient.ts
import { QueryClient } from '@tanstack/react-query'
export const queryClient = new QueryClient({
defaultOptions: {
queries: {
// 数据缓存配置
staleTime: 5 * 60 * 1000, // 5分钟内数据被认为是新鲜的
gcTime: 30 * 60 * 1000, // 30分钟后清理未使用的数据
// 重试配置
retry: (failureCount, error) => {
// 对于 404 错误不重试
if (error.status === 404) return false
// 最多重试 3 次
return failureCount < 3
},
retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000),
// 自动重新获取配置
refetchOnWindowFocus: true,
refetchOnReconnect: true,
refetchOnMount: true,
// 网络模式
networkMode: 'online', // 'online' | 'always' | 'offlineFirst'
},
mutations: {
retry: 1,
networkMode: 'online',
},
},
})
2.5 第一个查询示例
创建 API 函数
首先创建一个 API 服务文件 src/services/api.ts：
// src/services/api.ts
export interface User {
id: number
name: string
email: string
username: string
}
export interface Post {
id: number
title: string
body: string
userId: number
}
// 模拟 API 调用
const API_BASE = 'https://jsonplaceholder.typicode.com'
export const fetchUsers = async (): Promise => {
const response = await fetch(`${API_BASE}/users`)
if (!response.ok) {
throw new Error('获取用户列表失败')
}
return response.json()
}
export const fetchUser = a 
