目录前言一、TanStack QueryReact Query v4)1、从 React Query 到 TanStack Query 之间的变化二、react-query 的核心 API1、查询核心 API获取服务器状态1、useQuery() — React Query 的灵魂 API2、useInfiniteQuery() — 无限加载 / 下拉加载更多3、useSuspenseQuery() — 和 React Suspense 结合新趋势2、Mutation 核心 API提交数据、写入服务器1、useMutation() — 提交数据、写操作POST/PUT/DELETE2、useSuspenseMutation() — Suspense 的 mutation 版本3、Query Client全局控制器API1、queryClient.fetchQuery() — 手动触发查询常用于 SSR2、queryClient.invalidateQueries() — 主动重刷缓存非常关键3、queryClient.refetchQueries() — 主动重新获取立即刷新4、queryClient.setQueryData() — 手动更新缓存无网络5、queryClient.getQueryData() — 读取缓存不会触发请求6、queryClient.prefetchQuery() — 预取数据页面切换变快4、Queries / Mutations 事件与生命周期 API1、onSuccess / onError / onSettled2、onMutate乐观更新5、React Query Provider 核心 API1、QueryClientProvider — React Query 根提供器2、Hydration / dehydrate() — SSR/SSG 核心能力6、开发工具相关 API1、ReactQueryDevtools三、安装注册 react-query四、使用 react-query1、定义获取数据的查询函数 fetchTodos2、使用 useQuery 获取服务器状态3、新增数据useMutation 自动刷新列表4、删除数据useMutation 乐观更新5、组件组合五、React Query 能做什么不能做什么前言React Query 是“旧名称”只适用于 React。从 v4 版本开始React Query 团队把整个项目统一到 TanStack 品牌下并命名为 TanStack Query。TanStack Query 体系更加丰满了。不仅支持 React 的库了而且还是跨框架的通用查询管理系统。比如vue-query、svelte-query、solid-query等。React Query 是一个用于管理服务端状态的强大 React 库它的核心作用是让获取、缓存、同步和更新服务器数据变得简单高效。一、TanStack QueryReact Queryv4)React Query TanStack Query for ReactReact 专用版本TanStack Query 是整个家族React Query 是 TanStack Query 家族一员——在 React 上的实现——React Query 现在正式名为tanstack/react-query。React Query 从 v4 版本开始采用 “新体系”并更名为 TanStack Query。TanStack Query 不再仅支持 React 的库而是跨框架的通用查询管理系统框架对应的包Reacttanstack/react-queryVuetanstack/vue-querySveltetanstack/svelte-querySolidtanstack/solid-queryAngular实验tanstack/angular-queryTanStack 品牌/生态├── TanStack Query 核心库│ ├── tanstack/react-query ← React QueryReact版本│ ├── tanstack/vue-query│ ├── tanstack/svelte-query│ └── tanstack/solid-query│├── TanStack Table├── TanStack Router└── TanStack Virtual1、从 React Query 到 TanStack Query 之间的变化变化优点注意点 / 差异tanstack/react-query包名更正规、模块化、框架无关迁移时需要改 import网络模式 (networkMode)支持离线 在线策略需要调整默认的行为服务端缓存清理减少内存泄漏 / 挂起问题SSR 项目需注意 cacheTime 默认值Promise 取消方式改动使用标准AbortController更现代旧代码需要重构取消逻辑日志 API 改变更灵活、更现代旧日志方案不再可用跟踪查询 (tracked)减少无意义渲染提高性能影响使用notifyOnChangeProps的旧代码setQueryData更新逻辑增强优化乐观更新逻辑值为undefined时行为变化Mutation 缓存 GC减少内存不用手动管理需要了解 mutation 缓存机制React 18 支持并发特性、同步订阅更好升级 React 时更推荐 v4持久化机制完善支持 localStorage / 异步持久化迁移时需看接口兼容性通知事件简化订阅机制更清晰、统一自定义订阅代码需调整TS 升级需求类型更现代、对 ESM 支持强旧 TS 版本可能不兼容下面我们单从tanstack/react-query入手系统的学习下 TanStack Query 在 React 中的运用。二、react-query 的核心 APIReact Query 的核心 API 大致分为 3 大类查询Query、修改Mutation、客户端缓存控制QueryClient。1、查询核心 API获取服务器状态1、useQuery() — React Query 的灵魂 API用于获取服务器数据GET 请求。功能自动缓存自动重新请求自动错误处理自动状态loading, error, success自动垃圾回收示例const{data,isLoading,error}useQuery({queryKey:[todos],queryFn:fetchTodos,});这是 React Query 使用频率最高的 API。2、useInfiniteQuery() — 无限加载 / 下拉加载更多用于 分页加载、无限滚动 结构。示例constinfiniteuseInfiniteQuery({queryKey:[posts],queryFn:fetchPosts,getNextPageParam:(lastPage)lastPage.nextCursor,});3、useSuspenseQuery() — 和 React Suspense 结合新趋势示例const{data}useSuspenseQuery({queryKey:[user,id],queryFn:getUser,});当你未来结合 React 19 / SSR / streaming很实用。2、Mutation 核心 API提交数据、写入服务器1、useMutation() — 提交数据、写操作POST/PUT/DELETE用于所有 非 GET 请求。示例constmutationuseMutation({mutationFn:(newTodo)createTodo(newTodo),});包含的状态isPendingisSuccessisError2、useSuspenseMutation() — Suspense 的 mutation 版本很少用但和 Suspense 架构一致。3、Query Client全局控制器APIReact Query 所有操作都依赖 QueryClient。你在项目启动时创建它constqueryClientnewQueryClient();并注入 React 环境QueryClientProviderclient{queryClient}1、queryClient.fetchQuery() — 手动触发查询常用于 SSR服务器渲染或预取数据非常强大await queryClient.fetchQuery({queryKey:[posts],queryFn:fetchPosts,});2、queryClient.invalidateQueries() — 主动重刷缓存非常关键Mutation 后最常用的动作queryClient.invalidateQueries({queryKey:[todos]});场景新增 todo → 刷新列表更新用户信息 → 刷新关联页面3、queryClient.refetchQueries() — 主动重新获取立即刷新不同于 invalidate标记为过期refetch 立即执行。queryClient.refetchQueries({queryKey:[todos],});4、queryClient.setQueryData() — 手动更新缓存无网络用于 乐观更新 或 自定义缓存更新。queryClient.setQueryData([todos],old[...old,newTodo]);5、queryClient.getQueryData() — 读取缓存不会触发请求constdataqueryClient.getQueryData([todos]);6、queryClient.prefetchQuery() — 预取数据页面切换变快用在“鼠标悬浮预加载页面”的场景queryClient.prefetchQuery({queryKey:[profile],queryFn:fetchProfile,});React Router React Query 超流畅导航。4、Queries / Mutations 事件与生命周期 API1、onSuccess / onError / onSettled常用于 mutationuseMutation({mutationFn:updateUser,onSuccess:()queryClient.invalidateQueries([user])})2、onMutate乐观更新支持 乐观 UI 更新onMutate:async(newTodo){await queryClient.cancelQueries([todos]);constpreviousqueryClient.getQueryData([todos]);queryClient.setQueryData([todos],old[...old,newTodo]);return{previous};}5、React Query Provider 核心 API1、QueryClientProvider — React Query 根提供器所有 Query/Mutation 的前提QueryClientProviderclient{queryClient}2、Hydration / dehydrate() — SSR/SSG 核心能力Next.js、Remix 和 React 19 SSR 都需要 hydration APIdehydrate(queryClient)6、开发工具相关 API1、ReactQueryDevtools超级强大可实时查看缓存ReactQueryDevtoolsinitialIsOpen{false}/三、安装注册 react-query首先要安装 tanstack/react-querynpminstalltanstack/react-query然后在入口文件中必须加 QueryClientProvider// main.tsx / index.tsximport{QueryClient,QueryClientProvider}fromtanstack/react-query;importAppfrom./App;constqueryClientnewQueryClient();exportdefaultfunctionRoot(){return(QueryClientProvider client{queryClient}App//QueryClientProvider);}四、使用 react-query使用的 React Query 管理“服务器状态”的步骤获取数据useQuery创建数据useMutation更新与删除缓存、重新请求、乐观更新实战项目文件结构【举个例子】假设有一个服务器 API /api/todos。现在需要你实现以下需求①、获取 Todo 列表②、新增 Todo③、删除 Todo④、自动刷新、缓存、错误处理1、定义获取数据的查询函数 fetchTodos// api/todoApi.tsexportconstfetchTodosasync(){constresawaitfetch(/api/todos);if(!res.ok)thrownewError(Failed to fetch todos);returnres.json();};exportconstaddTodoasync(title:string){constresawaitfetch(/api/todos,{method:POST,body:JSON.stringify({title}),headers:{Content-Type:application/json}});if(!res.ok)thrownewError(Failed to add todo);returnres.json();};exportconstdeleteTodoasync(id:number){constresawaitfetch(/api/todos/${id},{method:DELETE});if(!res.ok)thrownewError(Failed to delete todo);returnres.json();};2、使用 useQuery 获取服务器状态import{useQuery}fromtanstack/react-query;import{fetchTodos}from./api/todoApi;exportfunctionTodoList(){const{data,isLoading,error}useQuery({queryKey:[todos],// 缓存 key全局唯一queryFn:fetchTodos,// 请求函数staleTime:5000,// 5 秒内不重新请求refetchOnWindowFocus:false,// 切回窗口不重新请求});if(isLoading)returndiv加载中.../div;if(error)returndiv加载失败/div;return(ul{data.map(todo(li key{todo.id}{todo.title}/li))}/ul);}3、新增数据useMutation 自动刷新列表import{useMutation,useQueryClient}fromtanstack/react-query;import{addTodo}from./api/todoApi;exportfunctionAddTodo(){constqueryClientuseQueryClient();constmutationuseMutation({mutationFn:(title:string)addTodo(title),onSuccess(){// 手动刷新 todos 列表queryClient.invalidateQueries([todos]);},});consthandleAdd(){mutation.mutate(新的任务);};return(button onClick{handleAdd}disabled{mutation.isPending}{mutation.isPending?添加中...:添加 TODO}/button);}4、删除数据useMutation 乐观更新React Query 的强大之处是可以不用等服务器响应先更新 UI失败再回滚import{useMutation,useQueryClient}fromtanstack/react-query;import{deleteTodo}from./api/todoApi;exportfunctionDeleteTodoButton({id}){constqueryClientuseQueryClient();constmutationuseMutation({mutationFn:()deleteTodo(id),// 乐观更新onMutate:async(){await queryClient.cancelQueries([todos]);constpreviousTodosqueryClient.getQueryData([todos]);queryClient.setQueryData([todos],(old:any[])old.filter(todotodo.id!id));return{previousTodos};},// 失败时回滚onError:(_err,_variables,context){queryClient.setQueryData([todos],context.previousTodos);},// 成功后真正拉取最新数据onSettled:(){queryClient.invalidateQueries([todos]);},});return(button onClick{()mutation.mutate()}删除/button);}5、组件组合exportdefaultfunctionApp(){return(divh1Todo 管理React Query/h1AddTodo/TodoList//div);}五、React Query 能做什么不能做什么负责管理“服务器状态”的难点缓存后台刷新自动请求合并乐观更新错误恢复对象引用稳定性重新请求策略全局状态同步不处理本地 UI 状态modal 是否打开表单状态跨组件 UI 状态这些 React Query 不能处理的可以适当选用useState/useReducer/Zustand之一来处理。