前端技术15-useEffect里写请求？TanStack Query让你告别数据获取地狱，从手动请求到智能缓存：我们的API调用减少了80%-创锋一号

「知识图谱生成工具」：一键将文件夹内容变身为交互式知识图谱的免安装桌面工具（文末附免费下载链接）-CSDN博客

你是否遇到过React里在useEffect里写数据请求，loading状态管理混乱，缓存逻辑自己实现的痛苦场景？数据获取本该简单，却被useEffect搞得复杂。网上搜到的TanStack Query教程要么太浅，要么没有深入最佳实践。本文将从原理到实战，给出一个零成本上手方案，包含完整代码和避坑指南。

📑 文章目录

写在前面：为什么你需要TanStack Query
核心概念三剑客：Queries、Mutations、Cache
服务器状态 vs 客户端状态：与Redux/Zustand的对比
实战：搭建企业级数据层
缓存策略深度解析
高级技巧：乐观更新、错误重试、分页加载
性能数据与真实案例
文末三件套

写在前面：为什么你需要TanStack Query

想象一下这个场景：

你在写一个用户列表页面。刚开始很简单——useEffect里调个API，设置个loading状态，完事儿。然后产品经理说：“加个刷新按钮”。好，你加了个refetch函数。接着：“用户切换tab回来要自动刷新”。行，你加了visibilitychange事件监听。然后：“这个列表要缓存，别每次都重新加载”。你开始写localStorage逻辑…

三个月后，你的组件变成了这样：

function UserList() { const [users, setUsers] = useState([]); const [loading, setLoading] = useState(false); const [error, setError] = useState(null); const [lastFetch, setLastFetch] = useState(Date.now()); const [retryCount, setRetryCount] = useState(0); const cacheRef = useRef(new Map()); // 200行代码后... return <div>我后悔了</div>; }

💡效率技巧：这时候你需要的是TanStack Query（原React Query），一个专门处理"服务器状态"的库。它把上面所有需求都封装好了，你只需要写一行代码：

const { data: users, isLoading } = useQuery(['users'], fetchUsers);

核心概念三剑客：Queries、Mutations、Cache

1. Queries（查询）—— 数据的"读取"操作

Queries用来获取数据。想象它是个智能管家：你告诉它"我要用户列表"，它会自动处理loading、error、缓存、重试…

import { useQuery } from '@tanstack/react-query'; // 基础用法 function UserList() { const { data, isLoading, error, refetch } = useQuery({ queryKey: ['users'], // 缓存的key，就像文件的文件名 queryFn: fetchUsers, // 实际获取数据的函数 staleTime: 5 * 60 * 1000, // 5分钟内数据视为"新鲜"，不重新请求 cacheTime: 10 * 60 * 1000, // 缓存保留10分钟 }); if (isLoading) return <div>加载中...</div>; if (error) return <div>出错了: {error.message}</div>; return ( <ul> {data?.map(user => <li key={user.id}>{user.name}</li>)} </ul> ); }

⚠️避坑警告：queryKey必须是可序列化的数组！不要用Date对象或函数作为key的一部分，否则会导致缓存失效问题。

// ❌ 错误：Date对象会导致每次渲染key都不同 useQuery({ queryKey: ['users', new Date()], // 每次渲染都是新的key！ queryFn: fetchUsers }); // ✅ 正确：用字符串或数字 useQuery({ queryKey: ['users', userId], // 稳定的key queryFn: () => fetchUser(userId) });

2. Mutations（变更）—— 数据的"写入"操作

Mutation处理POST、PUT、DELETE等修改操作。它提供了isLoading、isSuccess、isError等状态，以及mutate函数。

import { useMutation, useQueryClient } from '@tanstack/react-query'; function CreateUserForm() { const queryClient = useQueryClient(); const mutation = useMutation({ mutationFn: createUser, // 执行创建的API函数 onSuccess: () => { // 创建成功后，让users查询失效，自动重新获取 queryClient.invalidateQueries({ queryKey: ['users'] }); }, onError: (error) => { toast.error(`创建失败: ${error.message}`); } }); const handleSubmit = (values) => { mutation.mutate(values); }; return ( <form onSubmit={handleSubmit}> <input name="name" /> <button disabled={mutation.isLoading}> {mutation.isLoading ? '创建中...' : '创建用户'} </button> </form> ); }

💡效率技巧：invalidateQueries是"智能刷新"的关键。它不会立即重新请求，而是标记缓存为"过期"，下次组件渲染时自动获取最新数据。

3. Cache（缓存）—— 背后的"大脑"

TanStack Query的缓存系统是它的核心竞争力。看看这个架构图：

┌─────────────────────────────────────────────────────────────┐ │ TanStack Query Cache │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Query:users │ │ Query:user:1 │ │ Query:posts │ │ │ │ │ │ │ │ │ │ │ │ data: [...] │ │ data: {...} │ │ data: [...] │ │ │ │ state: fresh │ │ state: stale │ │ state: fresh │ │ │ │ updated: 2m │ │ updated: 10m │ │ updated: 30s │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ 状态流转: │ │ Fresh ──(staleTime)──> Stale ──(cacheTime)──> GC │ │ (新鲜) (过期) (垃圾回收) │ │ │ └─────────────────────────────────────────────────────────────┘

缓存的工作流程：

Fresh（新鲜）：数据刚获取，在staleTime内视为新鲜，不会重新请求
Stale（过期）：超过staleTime，数据过期但仍在缓存中，下次访问时后台自动刷新
Inactive（非活跃）：没有组件在使用这个查询
Garbage Collected（回收）：超过cacheTime的非活跃查询会被清理

服务器状态 vs 客户端状态：与Redux/Zustand的对比

这是一个经典的面试题，也是很多开发者困惑的地方。

什么是服务器状态？

服务器状态 = 存在于服务器上的数据，客户端只是"借来用用"。特点：

✅ 不由你控制（别人也能改）
✅ 需要异步获取
✅ 可能过期（stale）
✅ 需要缓存策略

什么是客户端状态？

客户端状态 = 只在客户端存在的数据。特点：

✅ 由你完全控制
✅ 同步更新
✅ 不需要缓存
✅ 例如：主题颜色、侧边栏展开状态、表单临时数据

对比表格

┌─────────────────┬──────────────────────┬──────────────────────┐ │ 特性 │ TanStack Query │ Redux / Zustand │ ├─────────────────┼──────────────────────┼──────────────────────┤ │ 主要用途 │ 服务器状态管理 │ 客户端状态管理 │ │ 缓存策略 │ ✅ 内置完整支持 │ ❌ 需自己实现 │ │ 自动刷新 │ ✅ 窗口聚焦/重连 │ ❌ 不支持 │ │ 重试机制 │ ✅ 指数退避重试 │ ❌ 需自己实现 │ │ 分页/无限滚动 │ ✅ 内置支持 │ ❌ 需自己实现 │ │ 乐观更新 │ ✅ 内置支持 │ ✅ 可实现 │ │ 全局状态共享 │ ✅ 支持 │ ✅ 支持 │ │ 学习成本 │ 中等 │ 较高(Redux) │ │ 代码量 │ 极少 │ 较多 │ └─────────────────┴──────────────────────┴──────────────────────┘

最佳实践：两者结合

// store.js - Zustand管理客户端状态 import { create } from 'zustand'; export const useUIStore = create((set) => ({ sidebarOpen: false, theme: 'light', toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })), setTheme: (theme) => set({ theme }), })); // UserList.jsx - TanStack Query管理服务器状态 import { useQuery } from '@tanstack/react-query'; import { useUIStore } from './store'; function UserList() { // 客户端状态：侧边栏是否展开 const sidebarOpen = useUIStore((state) => state.sidebarOpen); // 服务器状态：用户列表 const { data: users } = useQuery({ queryKey: ['users'], queryFn: fetchUsers, }); return ( <div className={sidebarOpen ? 'with-sidebar' : ''}> {users?.map(user => <UserCard key={user.id} user={user} />)} </div> ); }

💡效率技巧：记住这个口诀——“服务器用Query，客户端用Zustand”。两者不冲突，反而互补。

实战：搭建企业级数据层

项目结构

src/ ├── api/ │ ├── client.js # axios/fetch 实例配置 │ ├── users.js # 用户相关API │ └── posts.js # 文章相关API ├── hooks/ │ ├── queries/ │ │ ├── useUsers.js # 用户查询hooks │ │ └── usePosts.js # 文章查询hooks │ └── mutations/ │ ├── useCreateUser.js │ └── useUpdatePost.js ├── providers/ │ └── QueryProvider.jsx # QueryClientProvider配置 └── App.jsx

1. 配置QueryClient

// providers/QueryProvider.jsx import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { ReactQueryDevtools } from '@tanstack/react-query-devtools'; // 企业级配置 const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 5 * 60 * 1000, // 5分钟视为新鲜 cacheTime: 10 * 60 * 1000, // 缓存保留10分钟 retry: 3, // 失败重试3次 retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000), refetchOnWindowFocus: true, // 窗口聚焦时刷新 refetchOnReconnect: true, // 网络重连时刷新 suspense: false, // 不使用Suspense模式（可按需开启） }, mutations: { retry: 1, // 变更操作只重试1次 }, }, }); export function QueryProvider({ children }) { return ( <QueryClientProvider client={queryClient}> {children} <ReactQueryDevtools initialIsOpen={false} /> </QueryClientProvider> ); }

⚠️避坑警告：不要把QueryClient定义在组件内部！每次渲染都会创建新的client，导致缓存全部丢失。

// ❌ 错误：QueryClient在组件内 function App() { const queryClient = new QueryClient(); // 每次渲染都新建！ return ( <QueryClientProvider client={queryClient}> <Router /> </QueryClientProvider> ); } // ✅ 正确：QueryClient在组件外 const queryClient = new QueryClient(); function App() { return ( <QueryClientProvider client={queryClient}> <Router /> </QueryClientProvider> ); }

2. API层封装

// api/client.js import axios from 'axios'; export const apiClient = axios.create({ baseURL: process.env.REACT_APP_API_URL, timeout: 10000, headers: { 'Content-Type': 'application/json', }, }); // 请求拦截器 apiClient.interceptors.request.use( (config) => { const token = localStorage.getItem('token'); if (token) { config.headers.Authorization = `Bearer ${token}`; } return config; }, (error) => Promise.reject(error) ); // 响应拦截器 apiClient.interceptors.response.use( (response) => response.data, (error) => { if (error.response?.status === 401) { // 统一处理未授权 window.location.href = '/login'; } return Promise.reject(error); } );

// api/users.js import { apiClient } from './client'; export const userApi = { getUsers: (params) => apiClient.get('/users', { params }), getUser: (id) => apiClient.get(`/users/${id}`), createUser: (data) => apiClient.post('/users', data), updateUser: (id, data) => apiClient.put(`/users/${id}`, data), deleteUser: (id) => apiClient.delete(`/users/${id}`), };

3. 自定义Hooks封装

// hooks/queries/useUsers.js import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'; import { userApi } from '../../api/users'; // 获取用户列表 export const useUsers = (params = {}) => { return useQuery({ queryKey: ['users', params], // params变化时自动重新请求 queryFn: () => userApi.getUsers(params), select: (data) => data.data, // 转换数据格式 }); }; // 获取单个用户 export const useUser = (id) => { return useQuery({ queryKey: ['user', id], queryFn: () => userApi.getUser(id), enabled: !!id, // id存在时才执行查询 select: (data) => data.data, }); }; // 创建用户 export const useCreateUser = () => { const queryClient = useQueryClient(); return useMutation({ mutationFn: userApi.createUser, onSuccess: () => { // 创建成功后刷新用户列表 queryClient.invalidateQueries({ queryKey: ['users'] }); }, }); }; // 更新用户 export const useUpdateUser = () => { const queryClient = useQueryClient(); return useMutation({ mutationFn: ({ id, data }) => userApi.updateUser(id, data), onSuccess: (_, variables) => { // 更新成功后刷新相关缓存 queryClient.invalidateQueries({ queryKey: ['users'] }); queryClient.invalidateQueries({ queryKey: ['user', variables.id] }); }, }); }; // 删除用户 export const useDeleteUser = () => { const queryClient = useQueryClient(); return useMutation({ mutationFn: userApi.deleteUser, onSuccess: () => { queryClient.invalidateQueries({ queryKey: ['users'] }); }, }); };

4. 在组件中使用

// components/UserManagement.jsx import { useUsers, useCreateUser, useUpdateUser, useDeleteUser } from '../hooks/queries/useUsers'; export function UserManagement() { const { data: users, isLoading, error } = useUsers({ page: 1, pageSize: 10 }); const createUser = useCreateUser(); const updateUser = useUpdateUser(); const deleteUser = useDeleteUser(); const handleCreate = (userData) => { createUser.mutate(userData, { onSuccess: () => { toast.success('用户创建成功！'); }, }); }; const handleUpdate = (id, data) => { updateUser.mutate({ id, data }); }; const handleDelete = (id) => { if (confirm('确定删除吗？')) { deleteUser.mutate(id); } }; if (isLoading) return <Skeleton />; if (error) return <ErrorMessage error={error} />; return ( <div> <UserForm onSubmit={handleCreate} isLoading={createUser.isLoading} /> <UserTable users={users} onUpdate={handleUpdate} onDelete={handleDelete} /> </div> ); }

缓存策略深度解析

staleTime vs cacheTime

这是最容易混淆的两个概念，用图来说明：

时间线 ────────────────────────────────────────────────────────> 请求 ──[fresh]──────[stale]──────────────────────[GC]─────────> │ │ │ │ staleTime │ │ cacheTime │ (5分钟) │ │ (10分钟) │ │ │ ▼ ▼ ▼ 数据新鲜 数据过期但可用 缓存清理 直接返回 返回旧数据+后台刷新 下次请求重新获取

属性	含义	默认值	建议值
`staleTime`	数据被视为"新鲜"的时间	0	根据数据变化频率设置
`cacheTime`	非活跃缓存保留时间	5分钟	通常 >= staleTime

💡效率技巧：

变化频繁的数据（如股票价格）：staleTime: 0
变化不频繁的数据（如用户配置）：staleTime: 5 * 60 * 1000
几乎不变的数据（如城市列表）：staleTime: Infinity

refetch策略

const { data, refetch } = useQuery({ queryKey: ['users'], queryFn: fetchUsers, // 何时自动重新获取 refetchOnMount: true, // 组件挂载时 refetchOnWindowFocus: true, // 窗口重新获得焦点时 refetchOnReconnect: true, // 网络重新连接时 // 轮询 refetchInterval: 5000, // 每5秒刷新一次 refetchIntervalInBackground: false, // 后台标签页是否继续轮询 }); // 手动刷新 <button onClick={() => refetch()}>刷新</button>

⚠️避坑警告：refetchInterval在后台标签页默认会继续执行！如果不需要，记得设置refetchIntervalInBackground: false，避免不必要的API调用。

预取数据（Prefetching）

const queryClient = useQueryClient(); // 鼠标悬停时预取 <button onMouseEnter={() => { queryClient.prefetchQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId), staleTime: 10 * 1000, // 预取的数据10秒内视为新鲜 }); }} onClick={() => navigate(`/users/${userId}`)} > 查看详情 </button>

高级技巧：乐观更新、错误重试、分页加载

1. 乐观更新（Optimistic Updates）

乐观更新 = 先更新UI，再发请求。如果失败，回滚到之前的状态。

const queryClient = useQueryClient(); const updateTodo = useMutation({ mutationFn: updateTodoApi, // 1. 发送请求前：乐观更新UI onMutate: async (newTodo) => { // 取消正在进行的重新获取 await queryClient.cancelQueries({ queryKey: ['todos'] }); // 保存之前的状态（用于回滚） const previousTodos = queryClient.getQueryData(['todos']); // 乐观更新：直接修改缓存 queryClient.setQueryData(['todos'], (old) => old?.map((todo) => todo.id === newTodo.id ? { ...todo, ...newTodo } : todo ) ); // 返回上下文（用于onError回滚） return { previousTodos }; }, // 2. 请求失败：回滚到之前的状态 onError: (err, newTodo, context) => { queryClient.setQueryData(['todos'], context.previousTodos); toast.error('更新失败，已恢复之前状态'); }, // 3. 请求完成（无论成功失败）：重新获取确保数据一致 onSettled: () => { queryClient.invalidateQueries({ queryKey: ['todos'] }); }, });

💡效率技巧：乐观更新特别适合点赞、收藏等操作，给用户即时反馈，体验极佳。

2. 错误重试（Retry）

const { data, error } = useQuery({ queryKey: ['users'], queryFn: fetchUsers, // 基础重试 retry: 3, // 失败重试3次 // 自定义重试延迟（指数退避） retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000), // 条件重试：只对5xx错误重试，4xx不重试 retry: (failureCount, error) => { if (error.response?.status >= 500) { return failureCount < 3; } return false; // 4xx错误不重试 }, });

3. 分页加载（Pagination）

import { useQuery } from '@tanstack/react-query'; function PaginatedUsers() { const [page, setPage] = useState(1); const { data, isLoading, isPreviousData } = useQuery({ queryKey: ['users', page], queryFn: () => fetchUsers({ page, pageSize: 10 }), keepPreviousData: true, // 关键！切换页面时保持旧数据，避免闪烁 }); return ( <div> {isLoading && !isPreviousData ? ( <Skeleton /> ) : ( <UserList users={data?.list} /> )} <div className="pagination"> <button onClick={() => setPage(p => Math.max(p - 1, 1))} disabled={page === 1} > 上一页 </button> <span>第 {page} 页</span> <button onClick={() => setPage(p => p + 1)} disabled={!data?.hasMore || isPreviousData} > 下一页 </button> </div> </div> ); }

4. 无限滚动（Infinite Scroll）

import { useInfiniteQuery } from '@tanstack/react-query'; function InfiniteUserList() { const { data, fetchNextPage, hasNextPage, isFetchingNextPage, status, } = useInfiniteQuery({ queryKey: ['users'], queryFn: ({ pageParam = 1 }) => fetchUsers({ page: pageParam, pageSize: 20 }), getNextPageParam: (lastPage) => { // 返回下一页的参数 return lastPage.hasMore ? lastPage.nextPage : undefined; }, }); // 监听滚动到底部 const observerRef = useRef(); const lastElementRef = useCallback((node) => { if (isFetchingNextPage) return; if (observerRef.current) observerRef.current.disconnect(); observerRef.current = new IntersectionObserver((entries) => { if (entries[0].isIntersecting && hasNextPage) { fetchNextPage(); } }); if (node) observerRef.current.observe(node); }, [isFetchingNextPage, hasNextPage, fetchNextPage]); return ( <div> {data?.pages.map((page, pageIndex) => ( <React.Fragment key={pageIndex}> {page.list.map((user, index) => { const isLastItem = pageIndex === data.pages.length - 1 && index === page.list.length - 1; return ( <UserCard key={user.id} user={user} ref={isLastItem ? lastElementRef : null} /> ); })} </React.Fragment> ))} {isFetchingNextPage && <LoadingMore />} </div> ); }

性能数据与真实案例

我们的实际收益

在我们团队的中后台管理系统中，引入TanStack Query后：

┌────────────────────┬─────────────┬─────────────┬────────────┐ │ 指标 │ 改造前 │ 改造后 │ 提升 │ ├────────────────────┼─────────────┼─────────────┼────────────┤ │ API调用次数 │ 100% │ 20% │ ↓80% │ │ 代码行数（数据层） │ 100% │ 50% │ ↓50% │ │ 缓存命中率 │ 0% │ 95%+ │ ↑95% │ │ 首屏加载时间 │ 2.5s │ 1.2s │ ↓52% │ │ 重复请求bug数 │ 12个/月 │ 0个/月 │ ↓100% │ └────────────────────┴─────────────┴─────────────┴────────────┘

为什么API调用能减少80%？

组件级去重：同一页面多个组件请求相同数据，只发一次请求
智能缓存：返回已缓存的数据，不再重复请求
后台刷新：数据过期时后台静默刷新，不影响用户体验
预取：用户操作前提前加载数据

代码量减少50%从何而来？

改造前（手动管理）：

function UserList() { const [users, setUsers] = useState([]); const [loading, setLoading] = useState(false); const [error, setError] = useState(null); const [retryCount, setRetryCount] = useState(0); useEffect(() => { let cancelled = false; const fetchData = async () => { setLoading(true); setError(null); try { const data = await fetchUsers(); if (!cancelled) setUsers(data); } catch (err) { if (!cancelled) { setError(err); if (retryCount < 3) { setTimeout(() => setRetryCount(c => c + 1), 1000 * 2 ** retryCount); } } } finally { if (!cancelled) setLoading(false); } }; fetchData(); return () => { cancelled = true; }; }, [retryCount]); // ... 还要处理缓存、刷新、错误边界 ... return <div>...</div>; }

改造后（TanStack Query）：

function UserList() { const { data: users, isLoading, error } = useQuery({ queryKey: ['users'], queryFn: fetchUsers, }); return <div>...</div>; }

文末三件套

1. 【源码获取】

关注此系列获取后续更新，后台回复’TanStack’获取完整源码链接。包含：

企业级QueryClient配置
完整的API层封装示例
常用自定义Hooks合集
乐观更新、分页、无限滚动完整代码

2. 【思考题】

你的数据获取逻辑够优雅吗？试着回答这几个问题：

你的项目里有多少重复的useEffect + fetch代码？
当用户快速切换页面时，你的应用会发出多少重复请求？
如果网络不稳定，你的错误处理机制足够健壮吗？
数据更新后，你是如何确保所有相关组件都刷新的？

3. 【系列预告】

下一篇《Zustand轻量级状态管理》，我们将探讨：

为什么Zustand比Redux更适合现代React项目
如何用Zustand替代80%的Context使用场景
TanStack Query + Zustand的黄金组合实践

总结

TanStack Query不是来替代Redux或Zustand的，而是来解决一个特定问题的：服务器状态管理。它把数据获取中最麻烦的部分——缓存、重试、刷新、去重——都封装好了，让你专注于业务逻辑。

记住这几个核心要点：

Queries读，Mutations写—— 分工明确
queryKey是缓存的身份证—— 设计好key结构
staleTime控制新鲜度，cacheTime控制存活期—— 别搞混
乐观更新给用户即时反馈—— 体验翻倍
和Zustand搭配使用—— Query管服务器，Zustand管客户端

⚠️最后的避坑警告：不要试图用TanStack Query管理所有状态！表单状态、UI状态、主题设置这些客户端状态，还是交给Zustand或useState更合适。

CSDN标签: TanStack Query, React Query, 数据获取, 状态管理, React, JavaScript, 缓存

参考链接:

TanStack Query官方文档
React Query最佳实践

企业官网建设流程全解析