如果你跟我一样这几年在前端项目里反复写 loading、error、data 三件套那你大概率也经历过这种场景页面越做越多接口请求的重复代码越来越多最后每个组件里都塞满了一堆 useState、useEffect 和 axios 调用。一开始我觉得这只是业务需要后来换了几次项目、接手过几个老系统才意识到问题出在根上——我们一直在手动管理服务器状态而这件事根本不该由业务组件来操心。TanStack Query 解决的就是这件事。它不是为了替代 axios而是把接口数据的获取、缓存、更新、失效这些和 UI 无关的脏活累活都接管过去。我最近把一个老项目的数据层整体换成了 TanStack Query改造完之后代码量少了一大截接口重复请求消失页面切换也不再有那种闪一下 loading的廉价感。这篇文章就从实际使用出发讲讲我为什么推荐前端项目都该用 TanStack Query以及你在接入时会遇到的关键点、坑位和实操方案。如果你正被接口状态管理折磨或者想给下一个项目选个靠谱的方案这篇应该能帮你省不少时间。1. 传统请求管理方式的痛点为什么手动管接口撑不住项目变大1.1 每个页面都在重复造轮子现在的接口请求绝大多数还是拿数据和改数据两类。拿数据要处理加载中、空数据、报错、重试改数据要处理提交中、成功提示、失败回滚。这两类逻辑在每个具体页面里长得都差不多但因为没有统一的抽象大家只能每个页面复制一份。我见过很多代码长这样const [data, setData] useState(null); const [loading, setLoading] useState(false); const [error, setError] useState(null); useEffect(() { setLoading(true); fetchOrderList(params) .then((res) setData(res)) .catch((err) setError(err)) .finally(() setLoading(false)); }, [JSON.stringify(params)]);这套写法的第一个问题就是组件一多状态就被拆得七零八落。尤其是列表页加详情页再加一个编辑弹窗好几处都要用到同一份订单数据你没法保证它们拿到的数据是同一个版本。为了同步很多人开始把数据塞进全局 store然后专门写 action 去触发请求再写 reducer 维护三个字段的状态。store 越写越胖一个接口动辄牵扯四五个文件最后维护成本高得离谱。1.2 自定义 axios 封装救不了状态有团队意识到问题后会选择封装一层 useRequest 之类的自定义 Hook把 loading、error、data 收敛到一个函数里。这个方向是对的但做起来很难做好。因为你会发现光有请求还不够你还需要解决下面这些问题两个组件同时用到同一份数据要不要合并请求合并了之后怎么通知两边同时更新用户切走页面再切回来是重新请求还是用旧缓存编辑成功之后哪些相关查询需要失效并自动刷新轮询接口怎么实现才不浪费流量数据长时间不用内存里的缓存什么时候清掉这些问题听着不起眼一旦项目上规模每一个都是坑。我见过自己封装请求 Hook 的团队一开始很爽后来为了支持缓存和并发去重在内部加了一个 Map 存 promise又为了支持失效更新加了一套中心化的事件通知。说白了就是在重新发明轮子——而且轮子还未必比 TanStack Query 圆。1.3 服务器状态和客户端状态从头就没分清楚传统的开发习惯里我们把接口返回的数据和用户输入的临时数据混在一套 useState 里管理。但这两类数据本质上是不同的客户端状态是即时的、可变的比如弹窗开没开、表单填到哪一步服务器状态则是异步的、共享的而且它有一个重要特征——会过期。你无法完全掌握服务器端的数据什么时候变了所以本地这份拷贝天然就是不可信的。TanStack Query 的逻辑就是专门管理这类不可信的、异步的、共享的服务器状态。它把缓存、过期时间、请求失败重试、窗口聚焦重新获取这些机制全部内置而开发者只需要告诉它我的数据从哪儿来。2. 核心概念拆解queryKey、缓存与状态机的正确理解2.1 把接口数据看作缓存而不是变量想用好 TanStack Query最重要的是心态上的转变。以前写代码接口返回的数据是某个组件的私有财产现在要把它理解成一份全局缓存——任何组件都能访问只要 key 一样拿到的就是同一份数据。这个思路和数据库的缓存层很像。TanStack Query 内部会维护一个查询缓存池每个查询由 queryKey 唯一标识。当你调用useQuery时它会先去缓存池里找有没有对应的数据如果没有就执行 queryFn 发起请求如果有并且没过期就直接把缓存返回给组件。我的经验是把 queryKey 当作接口 参数的天然序列化。比如用户信息接口可以写成[user, userId]订单列表可以写成[orders, { page: 1, status: done }]。注意对象会被自动序列化所以参数的顺序无关紧要但内容变了 key 就会变这是后面做缓存拆分的基础。2.2 staleTime 和 gcTime两个被默认值坑过的参数这两个参数是 TanStack Query 里最重要的配置也是最容易被忽视的。简单说staleTime 表示数据从新鲜变为过期的时长。在过期之前任何组件读取都会直接用缓存不会发请求。gcTime 表示数据从不再被使用到真正从内存里清除的时长。默认是 5 分钟。默认情况下 staleTime 是 0也就是说数据被拿到手的那一刻就已经过期了。一旦有过期数据存在组件重新挂载或者窗口重新聚焦时就会触发后台重新请求。对很多项目来说这个默认行为反而会造成不必要的频繁请求。我实际项目里一般会根据业务设置 staleTime。比如用户基本信息这类低频变化数据设 5 分钟订单列表这种中等频率的数据设 30 秒只有实时性要求高的才设为 0。设置之后你会发现无意中少了一大批请求页面切换也不会再疯狂转 loading。注意staleTime 设大不代表数据永远不更新。手动调用 invalidateQueries 或者 refetch 时照样可以强制刷新。它只是控制自动重新请求的触发条件。2.3 isLoading 与 isFetching 的区别很多人一直用错接触 TanStack Query 之后最先要抛弃的一大习惯就是所有请求都看 loading。它区分了两个非常关键的布尔值isFetching任何一次请求正在进行中。包括后台静默刷新、分页加载、手动 refetch。isLoading当前没有任何数据并且正在首次加载。举个例子一个列表页已经加载过第一页了用户点击翻页。此时 isFetching 是 true但如果数据还没拿到手之前你难道要把整个页面变成空白 loading 吗显然不合理。正确做法是保留旧数据只在局部显示加载指示器。这背后的设计哲学是服务器状态在大部分时间都有上一次成功的数据可以使用。既然有旧数据就没必要让用户面对空白。TanStack Query 用 placeholderData 或者 keepPreviousData 来做这件事具体细节下面实战部分会展开。3. 实战案例把一个真实项目的数据层接入 TanStack Query3.1 五步搭好基础环境我用 React 项目举例Vue 项目用 tanstack/vue-query思路完全一样。第一步是安装依赖npm i tanstack/react-query第二步创建全局 QueryClient 并设置默认参数。我习惯把重试次数、缓存时间、请求失败回调都放在这一层统一配置import { QueryClient } from tanstack/react-query; export const queryClient new QueryClient({ defaultOptions: { queries: { retry: 2, staleTime: 30 * 1000, gcTime: 5 * 60 * 1000, refetchOnWindowFocus: false, }, }, });第三步在应用入口用 QueryClientProvider 包裹import { QueryClientProvider } from tanstack/react-query; createRoot(document.getElementById(root)!).render( QueryClientProvider client{queryClient} App / /QueryClientProvider );第四步写一个最小的查询组件function UserInfo({ userId }: { userId: string }) { const { data, isLoading, error } useQuery({ queryKey: [user, userId], queryFn: () fetchUser(userId), }); if (isLoading) return div加载中.../div; if (error) return div加载失败/div; return div{data.name}/div; }第五步把之前 useEffect 里手动拉数据的代码全部删掉。这句很关键——只要你接入了 TanStack Query页面里 90% 的使用Effect拉接口的代码都不需要了。3.2 分页列表的缓存与预取让翻页不再白屏分页列表是管理后台最常见的场景。传统写法每次翻页都把 data 清空重新走后一遍 loading。用 TanStack Query 之后你可以让上一页的数据留在界面上直到新数据到达const [page, setPage] useState(1); const { data, isFetching, isPlaceholderData } useQuery({ queryKey: [projects, page], queryFn: () fetchProjects(page), placeholderData: keepPreviousData, });这里的placeholderData: keepPreviousData是一个很实用的 API当 queryKey 从[projects, 1]变成[projects, 2]的瞬间因为第二页还没有缓存useQuery 会把第一页的数据作为占位数据返回给你同时 isPlaceholderData 为 true。这样界面不会闪白你可以在表格顶部显示一个细小的进度条提示用户正在加载下一页。配合预取体验还能再上一个台阶。用户在第一页停留的时候就可以提前把第二页请求出来const queryClient useQueryClient(); useEffect(() { void queryClient.prefetchQuery({ queryKey: [projects, page 1], queryFn: () fetchProjects(page 1), }); }, [page, queryClient]);用户点下一页时数据早就躺在缓存里了页面几乎是瞬间渲染完全感觉不到网络延迟。这个效果用传统的分页组件实现需要写很多协调代码而 TanStack Query 这边只需要十几行。3.3 乐观更新让操作快人一步乐观更新指的是在接口还没返回时先在本地把 UI 改成成功后的状态等接口真正成功后再把服务端数据同步回来如果接口失败就回滚到之前的状态。最典型的场景是点赞、收藏、修改标题。用 useMutation 实现非常顺const queryClient useQueryClient(); const mutation useMutation({ mutationFn: (newTitle: string) updateProjectTitle(projectId, newTitle), onMutate: async (newTitle) { await queryClient.cancelQueries({ queryKey: [project, projectId] }); const previous queryClient.getQueryData([project, projectId]); queryClient.setQueryData([project, projectId], (old) ({ ...old, title: newTitle, })); return { previous }; }, onError: (_err, _newTitle, context) { queryClient.setQueryData([project, projectId], context.previous); }, onSettled: () { queryClient.invalidateQueries({ queryKey: [project, projectId] }); }, });这里我解释一下每一步在干嘛。onMutate 里先取消可能正在进行的请求防止旧的响应把乐观更新覆盖掉然后取出之前的缓存再把新的标题写入缓存如果失败onError 里把旧数据写回去最后不管成功失败onSettled 里都要让这个 key 对应的查询失效触发一次后台重新拉取保证和服务端最终一致。注意乐观更新适合用户体验要求高、失败概率低的操作。像删除订单这种高风险操作还是要等接口返回成功后再更新数据。3.4 轮询、重试与手动刷新配置项用好就是效率翻倍实时性要求高的页面比如大屏监控、待办数量可以用 refetchInterval 做轮询。不需要自己 setInterval它自己会处理清理和生命周期useQuery({ queryKey: [todoCount], queryFn: fetchTodoCount, refetchInterval: 5000, });请求失败时默认会重试 3 次。我建议在网络环境复杂的产品里把重试次数和间隔重新配置一下const queryClient new QueryClient({ defaultOptions: { queries: { retry: (failureCount, error) { if (error instanceof HttpError error.status 400 error.status 500) { return false; } return failureCount 3; }, retryDelay: (attempt) Math.min(1000 * 2 ** attempt, 30000), }, }, });4xx 的请求错误基本是参数或权限问题再怎么重试也不会成功不如直接返回。5xx 和网络错误才值得重试而且用指数退避的方式避免把服务端打崩。至于手动刷新一个 mutation 或 refetch 方法就搞定了不需要额外写状态。4. 选型决策与团队协作为什么说这不只是一个请求库4.1 它接管了状态管理里最麻烦的那部分不少人一听接口请求管理第一反应是我直接用 axios 就行。但 TanStack Query 的定位比请求库高一层。它管的是数据从请求到缓存到展示到更新的整个生命周期。我以前也用过 Redux 管理接口数据那滋味很酸爽要在 store 里定义 state、action、reducer、dispatch还要处理异步的 thunk/saga。数据一多查一个 bug 要沿着一整条链路点半天。而 TanStack Query 的思路是配置式的声明 queryKey 和 queryFn剩下交给它处理。这大幅减少了状态管理的心智负担——大部分接口数据其实没那么多全局共享的需求根本不需要进 store。把两个方案摆在团队里比较新成员上手成本也非常明显。TanStack Query 的写法几乎没有内部规范的空间照着文档写就行。而自研方案往往依赖项目里约定的一堆 store 目录、action 文件命名规则新人踩坑率很高。4.2 Devtools 是排查问题的神器TanStack Query 提供了官方的开发者工具可以直接查看所有缓存的查询、状态、请求耗时、提交和请求频率。import { ReactQueryDevtools } from tanstack/react-query-devtools; QueryClientProvider client{queryClient} App / ReactQueryDevtools / /QueryClientProvider我看缓存时最常用的几个信息状态fresh / fetching / stale / inactive能直观看到哪些数据是新的、哪些过期了。请求耗时定位慢接口很好用。查询键树展开之后能清楚看到 key 的结构检查有没有写错。缓存数据区直接看内存里存的值长什么样不用打 console.log。在开发环境开着 Devtools排查接口问题效率会高出不少。某种程度上这也倒逼项目把接口数据的 CRUD 做得更规范。4.3 什么场景不适合用 TanStack Query虽然我非常推荐但也不是所有项目都该无脑上。我帮你们划一下边界纯 SSR 页面、几乎没有交互的小型官网用 React Query 反而引入不必要的依赖。实时双向通信场景比如聊天室、实时白板、协同编辑这些本质是 websocket 推送不是客户端发起的请求-响应模式TanStack Query 帮不上忙。极简的组件内单次请求如果页面只有一两个接口也不存在跨组件共享手动 useRequest 就够了。绝大多数中后台管理系统、B 端产品、带列表详情编辑流程的应用都属于非常合适用的范畴。如果你正在做这类项目早点接入是在节省时间。5. 常见问题与排查技巧实录5.1 接口数据更新了但页面就是不刷新这是刚上手时最常撞的坑。原因基本是缓存没失效。TanStack Query 不会在每次接口数据变化时自动感知它只会根据 queryKey 和 staleTime 决定要不要重新请求。解决方案是在 mutation 成功之后主动让相关查询失效const mutation useMutation({ mutationFn: createOrder, onSuccess: () { queryClient.invalidateQueries({ queryKey: [orders] }); }, });这样所有以[orders]开头的查询都会标记为过期重新挂载或后台自动刷新时就会拉取新数据。如果你设置了 staleTime 很长又要立即刷新可以使用 refetchawait queryClient.refetchQueries({ queryKey: [orders] });5.2 接口被重复请求跟预期不一样TanStack Query 在同一时间对同一 queryKey 的请求会自动合并也就是说 10 个组件同时调用同一个查询只会发一次请求。但如果你真看到重复请求先检查是不是不小心把 queryKey 写成了不同值。比如订单列表有人写成[orders]有人写成[orderList]还有人写[orders, undefined]这三个 key 会被当成三个完全不同的缓存自然就会发多次请求。我习惯把接口 URL 作为 key 的第一段参数作为第二段整个项目统一这个规则基本能避免这类问题。另外queryKey 里如果有对象TanStack Query 会做深比较。如果你在 render 里临时创建了一个新对象字面量而且字段每次都不一样比如无意义的 Date.now()那么 key 永远不稳定会导致无限循环请求。这是最容易排查不出来的 bug 之一我踩过一次后来写 queryKey 就会刻意避免放不稳定的字段。5.3 v4 和 v5 的差异升级前先看两眼如果你之前用的是 React Query v3/v4升级到 TanStack Query v5 有一些破坏性变更。这里列几个我在升级时踩过的主要差异版本差异v3/v4v5包名react-querytanstack/react-queryuseQuery 回调onSuccess 可以直接在 useQuery 里写useQuery 上的 onSuccess 已废弃分页占位keepPreviousData 单独导出传入 options从 tanstack/react-query 导入 keepPreviousData 函数传入 placeholderDatauseMutation 回调同样支持 onSuccessonSuccess 仍然支持但建议用 onSettledv5 把选项统一为对象式传参对 TypeScript 的推断也更友好。如果新项目直接用 v5 就好老项目升级时重点检查 useQuery 的 onSuccess 和 keepPreviousData 这两处改动。5.4 一个速查表被问得最多的问题及解决方案现象原因解决方案页面一直显示旧数据staleTime 太长缩短 staleTime或手动 invalidateQueries / refetch接口疯狂重复请求queryKey 不稳定或包含变化值排查 queryKey 内容确保稳定可序列化多个组件重复发同类请求queryKey 写法不统一统一 key 规则或检查 key 参数是否一致切换页面后 loading 闪烁未使用缓存占位使用 placeholderData 或 keepPreviousData请求失败后一直无提示retry 次数太多配置 retry 逻辑4xx 不重试并统一报错处理组件卸载后还在发请求useEffect 里手动请求未取消删除手动 useEffect 请求代码交给 useQuery 管理按这套排查逻辑基本能覆盖日常使用中 90% 的问题。剩下的大概率就是某个参数确实设置得和业务预期不匹配调整配置就能解决。在我自己把新项目的数据层切换到 TanStack Query 之后最大的感受不是少写了多少代码而是整个团队对数据什么时候更新这件事的认知被拉齐了——不需要再靠人脑维护一份 store 状态流转也省去了大量和 loading 状态较劲的时间。哪怕你短期内只拿它管理一两个列表页长期看也值。如果正在规划下一个前端项目我建议给它一次机会用一周时间做个小的并行试点应该很快就能体会到差距。