搞前端的人，谁还没在项目里写过一堆useState加useEffect去拉接口的样板代码。数据加载中、报错了、成功拿到数据了、又要刷新了、又要翻页了，每个列表页都来一遍，写的时候不觉得，等项目大了就知道有多痛。TanStack Query（以前叫 React Query）就是来收拾这个烂摊子的。它不是发请求的库，发请求你用 axios、fetch 都行，它管理的是请求拿回来的那堆数据和请求过程的状态。
这篇文章我不打算念文档，只聊我在真实项目里用 TanStack Query 做查询功能时的核心思路、拆解逻辑、实操步骤和踩过的坑。你要是正在做后台管理系统、数据看板或者任何前端要频繁跟后端要数据的项目，这文章应该能帮你省不少时间。
1. 查询功能的设计思路与核心概念拆解
TanStack Query 能成为 React 生态里服务端状态管理的标配，不是因为它封装得好，而是它的设计模型本身就切中了前端查询场景的痛点。我们先把它最核心的几个概念掰开揉碎了看。
1.1 查询键（Query Key）才是真正的缓存地址
很多初学者用 TanStack Query 容易忽略查询键的设计，觉得随便写个字符串就行。实际上查询键就是缓存的物理地址，它决定了你这次查询的数据会被存放在哪里，以及什么时候会被命中。
查询键本质上是个数组，数组里的每一项可以是字符串、数字、对象甚至嵌套对象。TanStack Query 内部会对这个数组做稳定的哈希计算，比如['users', { page: 1, size: 20 }]和['users', { size: 20, page: 1 }]，只要对象内部的键值对一致，哈希结果就一样，会被视为同一个查询。这一点很贴心，因为我们在代码里写对象字面量时，属性顺序往往是随手写的，如果顺序不同就算不同缓存，那缓存命中率会惨不忍睹。
设计查询键的原则是：把影响返回结果的参数全部放进键里，并且保持结构稳定。例如查询用户列表，如果有筛选条件，就应该写成['users', 'list', { status, role, keyword }]，而不是['users', status, role, keyword]。前一种写法用字符串分段来区分数据类型，后续做部分缓存更新时定位更清晰。我做项目时习惯把查询键抽成常量或者工厂函数，比如userKeys.list(filters)返回['users', 'list', filters]，userKeys.detail(id)返回['users', 'detail', id]。这样在别处做queryClient.invalidateQueries(userKeys.list())时，代码可读性会高很多，也避免了字符串散落各处导致改一个名字要全局搜索替换的尴尬。
1.2 查询函数是唯一的数据来源
查询函数负责返回一个 Promise，resolve 的结果就是缓存里存放的数据。这里有个新手容易踩的坑：查询函数里不要处理全局状态，也不要去读组件外部的可变变量，它应当是一个纯函数，数据结果只由查询键决定。
我之前调试过一个很诡异的 bug，同样的查询参数，有时候返回的数据是旧的，有时候是新的。排查了半天发现是查询函数里直接读取了一个模块级变量，而这个变量在别处被修改了。查询键没变，但查询函数执行结果变了，TanStack Query 出于性能考虑不会重新执行函数，自然就拿到了旧数据。正确的做法是把所有影响结果的变量全部挂在查询键上，查询函数里只做两件事：组装请求参数、调用接口并返回数据。
另外，如果请求失败，查询函数里应当抛出异常，而不是返回null或者undefined。TanStack Query 靠异常来判断这次查询是否失败，只有 reject 才会进入isError状态并触发重试机制。如果你用了try...catch把错误吃掉然后返回一个空值，那 TanStack Query 会以为请求成功了，UI 上明明没数据却不报错，排查起来非常让人抓狂。
2. 核心查询流程实操：从基础查询到依赖查询
理解了查询键和查询函数这两个基石，我们就能开始写实际的查询逻辑了。这一节我按使用频率从高到低，把最常用的几个查询模式过一遍，每个模式都说明适用场景和需要注意的细节。
2.1 基础列表查询：useQuery 的最简形态
列表查询是后台系统最常见的需求。假设我们从后端拉取一页用户数据，最基础的写法是这样：
import { useQuery } from '@tanstack/react-query' function UserList() { const { data, isLoading, isError, error, refetch } = useQuery({ queryKey: ['users', 'list'], queryFn: async () => { const res = await fetch('/api/users') if (!res.ok) throw new Error('Network response was not ok') return res.json() } }) }这个例子虽然简单，但已经涵盖了几个关键点。isLoading是初次加载时为true，data是查询成功后的数据，error是查询函数抛出的异常对象。很多教程会忽略对res.ok的检查，直接用res.json()。但 fetch 在 HTTP 状态码为 404、500 时并不会 reject，它照样会 resolve，如果你不手动判断res.ok并抛错，TanStack Query 永远不知道请求失败了。
实际项目中我建议把查询函数封装成统一的请求工具，比如在 axios 拦截器里统一处理状态码和错误提示，查询函数里直接调用http.get('/api/users')即可。这样组件代码会非常干净，查询函数只保留业务逻辑，网络层的细节全部下沉到基础设施里。
2.2 带参数的查询：动态查询键的正确姿势
列表通常都有筛选条件、分页参数。参数放在 query key 里，当参数变化时，TanStack Query 会自动重新执行查询函数。
function UserList({ page, pageSize, keyword }) { const { data, isLoading } = useQuery({ queryKey: ['users', 'list', { page, pageSize, keyword }], queryFn: async () => { const params = new URLSearchParams({ page, pageSize, keyword }) const res = await fetch(`/api/users?${params}`) if (!res.ok) throw new Error('Network response was not ok') return res.json() } }) }这里有个微妙的行为：当page从 1 变成 2 时，旧的['users', 'list', { page: 1 }]的数据并不会立即被清除，它会继续保留在缓存里，同时新的['users', 'list', { page: 2 }]查询开始加载。这就是 TanStack Query 的“基于键的缓存隔离”特性，每个键都是独立的缓存单元，互不干扰。
这种设计带来一个直接的 UX 优化空间：分页切换时，页面可以保持显示旧数据，同时后台加载新数据。默认情况下，isLoading只在没有任何缓存数据时才是true，如果切换页码后旧缓存还在，isLoading会是false，同时isFetching为true。UI 上可以用isFetching来显示一个顶部细进度条，而不是整个页面转圈，体验会流畅很多。
2.3 依赖查询：网络请求版的条件判断
前端经常会遇到“等某个数据成功后再请求另一个数据”的场景，比如先拿用户 ID，再根据 ID 查用户的订单。这时候需要用enabled选项来控制查询是否执行。
const { data: user } = useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId), }) const { data: orders, isLoading: ordersLoading } = useQuery({ queryKey: ['orders', user?.id], queryFn: () => fetchOrdersByUserId(user.id), enabled: !!user?.id, })enabled为false时，查询不会执行，状态保持pending，数据为undefined。一旦enabled变为true，查询自动触发。如果依赖的数据还没拿到，enabled是false，这个查询就一直处于休眠状态，不会浪费请求。
这种父子依赖的写法很常见。但要注意不要滥用，如果 A 和 B 两个接口之间没有真正的先后依赖关系，只是恰好都需要同一个参数，那就应该用并行查询而不是依赖查询，否则串行请求会拖慢整体加载速度。判断标准很简单：B 的请求参数是否真的需要 A 的响应结果来决定，如果不是，就别用enabled。
2.4 竞态处理：参数快速变化时的安全网
带参数的查询有一个隐藏的竞态风险。用户在一个带搜索框的列表页里快速输入文字，每敲一个字母，keyword变化一次，就触发一次查询。如果后端响应速度不稳定，先发出的请求可能比后发出的请求更晚返回，这时候展示的数据就有可能是旧的。
TanStack Query 对这个问题的处理是：每个查询键是独立缓存的，当你从['users', { keyword: 'a' }]切换到['users', { keyword: 'ab' }]时，两个请求都会发出，但 UI 上展示的是最后一个查询键对应的数据。也就是说，如果keyword: 'ab'的请求先返回，展示的就是ab的结果，之后keyword: 'a'的请求虽然返回了，但它写入的是自己的缓存，不会覆盖当前 UI 的数据。
这个机制帮我避免了很多手写useEffect时需要管理的“请求序号”之类的东西。不过还是要提醒一点，如果组件卸载了，查询结果写入缓存依然有效，这是正常的缓存行为，不要试图在卸载时阻止写入，否则会破坏缓存的全局共享性。
3. 进阶玩法：缓存更新、预取与分页优化
基础查询能覆盖 80% 的需求，但真正让 TanStack Query 发挥威力的是它处理缓存更新、预取数据和分页加载的能力。这部分用好了，后端的压力能小不少，前端的感知速度也会有质的提升。
3.1 新增数据的缓存更新：invalidateQueries 与 setQueryData 的选择
列表查询通常搭配新增、编辑、删除操作。操作完成后，最直接的做法是调用queryClient.invalidateQueries让列表重新请求：
const queryClient = useQueryClient() const mutation = useMutation({ mutationFn: (newUser) => createUser(newUser), onSuccess: () => { queryClient.invalidateQueries({ queryKey: ['users', 'list'] }) } })invalidateQueries会标记匹配到的查询为失效状态，同时立即重新执行这些查询函数。它做的事就是最可靠的“拉新数据”操作，因为你不用关心后端返回了什么消息，只要数据变了，列表就会重新拉一遍。
但有些场景 re-fetch 会显得浪费。比如用户点了“删除”按钮，列表里要移除那一行，局部的数据结构我们其实是知道的。这时候可以直接用setQueryData手动修改缓存：
const mutation = useMutation({ mutationFn: (userId) => deleteUser(userId), onSuccess: (_, userId) => { queryClient.setQueryData(['users', 'list', currentFilters], (old) => { return old.filter((user) => user.id !== userId) }) } })setQueryData直接改写缓存，不会发请求。这种做法在交互上非常快，因为删掉一行的响应是瞬间的。但风险是一旦你对数据结构的假设出错（比如后端在删除后对列表做了重排序），缓存就会和后端不一致，需要小心使用。
实际项目中我通常这样权衡：新增、编辑这类会改变整个列表排序或聚合结果的操作用invalidateQueries，删除这种明确知道哪一行消失的操作，且分页和筛选状态已知的情况下，用setQueryData做乐观更新。
3.2 预取数据：让接下来的页面秒开
预取是提升感知性能的利器。比如用户停在第一页看列表，你可以在鼠标 hover 到下一页按钮时就预取第二页的数据，用户真正点击时，数据已经在缓存里了，瞬间渲染。
function PaginationButton({ page }) { const queryClient = useQueryClient() const prefetchNextPage = () => { queryClient.prefetchQuery({ queryKey: ['users', 'list', { page: page + 1, pageSize: 20 }], queryFn: () => fetchUsers({ page: page + 1, pageSize: 20 }), staleTime: 10 * 1000, }) } return ( <button onMouseEnter={prefetchNextPage} onClick={...}> 下一页 </button> ) }prefetchQuery和useQuery的区别在于它不会订阅状态更新，只是一次性地把数据放到缓存里。如果prefetchQuery请求失败了，它不会触发 UI 报错，只是静默失败，用户真正点击时再用常规方式请求一遍。
这个技巧对列表页、详情页跳转特别有效。比如用户点击某一行查看详情，在onMouseEnter这一行时就可以预取详情接口的数据，用户点击后再进入详情页时，数据可能已经加载完成了。
3.3 无限滚动分页：useInfiniteQuery 的完整拆解
移动端或者后台系统的长列表，常用“滚动到底部加载更多”的交互。手写的话，你要自己和page状态、追加数组、判断还有没有下一页纠缠。TanStack Query 提供了useInfiniteQuery来专门处理这种场景。
import { useInfiniteQuery } from '@tanstack/react-query' function InfiniteUserList() { const { data, isLoading, isFetchingNextPage, fetchNextPage, hasNextPage, } = useInfiniteQuery({ queryKey: ['users', 'infinite'], queryFn: ({ pageParam }) => fetchUsers({ page: pageParam, pageSize: 20 }), initialPageParam: 1, getNextPageParam: (lastPage, allPages) => { return lastPage.hasMore ? allPages.length + 1 : undefined }, }) }在这个模式下，data的结构不再是数组，而是一个{ pages: [], pageParams: [] }的结构。pages数组里每一项是每次请求返回的数据。渲染时你需要手动把pages里的数组展开。
getNextPageParam函数接收最后一批数据和所有已加载的数据，返回下一页的参数。这里最常见的错误是在函数里写死了下一页的页码。如果接口返回的是游标而不是页码，应该返回游标值；如果根据“当前页数 < 总页数”来判断是否有下一页，应该用lastPage.currentPage + 1这样的逻辑，并在没有下一页时返回undefined。返回undefined时，hasNextPage会自动变成false，滚动到底部就不会再触发请求了。
无限滚动触发的时机一般是用一个 sentinel 元素配合 IntersectionObserver，也可以用滚动容器的scroll事件手动判断。不管用哪种方式，触发条件统一是hasNextPage && !isFetchingNextPage时才调用fetchNextPage()，否则用户快速滚动到底部多次会排队发起一堆无意义的请求。
4. 查询性能调优与请求策略
查询请求发得太多太少都是问题。发太多，后端扛不住，前端也白白浪费时间解析响应；发太少，数据新鲜度不够，用户看到的是过时信息。TanStack Query 提供了一整套参数来控制缓存的新鲜度、回收时机和窗口重新聚焦时的行为。
4.1 staleTime 与 gcTime：缓存的新鲜度和寿命
staleTime控制数据多久算“过时”，单位是毫秒。默认值为 0，意思是查询成功后，数据立刻变成过时状态，任何时候重新挂载组件都会重新请求。但实际项目中，绝大多数列表数据不需要这么频繁地刷新。
const { data } = useQuery({ queryKey: ['dashboard', 'stats'], queryFn: fetchDashboardStats, staleTime: 30 * 1000, })如果staleTime设为 30 秒，在这 30 秒内，组件重新挂载、窗口重新聚焦都不会发请求，直接用缓存数据。过了 30 秒再看，数据被视为过时，下次触发检查时才会重新请求。这个参数是“新鲜度保障”，不是“定时刷新器”，它语义是“数据在这段时间内一定是最新的，不需要再问”。
gcTime（以前叫cacheTime）控制缓存数据在内存中保留多久。含义是：当某个查询不再被任何组件订阅时，数据并不会立即从缓存中消失，而是继续保留一段时间，默认 5 分钟。如果用户在这段时间内重新访问这个查询，直接读缓存，不需要重新请求。5 分钟后仍未被订阅，缓存才被垃圾回收清除。
这两个时间参数很容易混淆，我习惯用一个生活化的类比：staleTime是“保质期”，在保质期内吃（用数据）不用检查；gcTime是“冰箱里能放多久”，即使没人吃（没有组件消费），只要没超过保存期限就不扔。合理设置staleTime可以显著减少请求数量，合理设置gcTime则可以提升用户回访时的加载速度。
4.2 窗口聚焦与重连时的重新请求
TanStack Query 默认会在浏览器窗口重新获得焦点时，把过时的查询重新刷新一遍。这个行为的出发点是：用户切出去几分钟又切回来，界面上的数据大概率已经过期，重新请求能保证数据新鲜。
实际项目中可以把refetchOnWindowFocus打开或关闭。有些内部管理系统，数据本身不太变化，这个默认行为反而会导致不必要的请求。设置成false就能完全关掉这个特性。
refetchOnReconnect控制网络从断线恢复时是否重新请求，默认是false。如果你的应用需要极强的数据一致性，可以打开。但要注意，网络恢复时所有过时查询同时刷新，可能会造成请求风暴。建议在需要的时候只针对关键查询单独设置，而不是全局打开。
4.3 请求重试策略：别让失败请求雪上加霜
默认情况下，TanStack Query 对失败的请求会重试 3 次，并且重试间隔逐渐延长（指数退避）。这个设计对偶发的网络抖动很友好，但有些接口的失败是业务性的，比如参数错误（400）或者权限不足（403），重试再多次结果也是一样的，纯属浪费。
const { data } = useQuery({ queryKey: ['user', userId], queryFn: fetchUser, retry: (failureCount, error) => { if (error.response?.status === 400 || error.response?.status === 403) return false return failureCount < 2 } })我在项目里一般会在请求工具层把 HTTP 状态码转换成对应的错误类型，然后在retry回调里根据错误类型决定是否重试。4xx 的请求一律不重试，5xx 和网络错误才重试。这样可以避免无效请求把服务器日志刷出噪音，也避免用户在权限不足时还看着界面转圈。
4.4 并行查询与依赖查询的边界把握
当页面需要同时请求多个互不依赖的接口时，有两种方式：多个useQuery并行执行，或者用Promise.all合并成一个查询函数。
多个useQuery的优点是每个查询独立缓存、独立加载状态，比如用户信息一个查询、统计数据一个查询，其中一个失败只影响对应的区块，其他区块正常渲染。缺点是组件代码里要多几个isLoading判断。但这不是什么大问题，拆开反而更灵活。
某些场景确实需要把多个请求合并成一个查询，比如详情页需要同时拿到用户信息和用户的权限配置，而这两个接口单独请求耗时都很短，合并成一个可以少一次网络往返。但这样做的代价是缓存粒度变粗，任何一个子接口数据变化时，整个查询都会重新加载。我通常不推荐这么用，除非接口本身就是一个聚合接口（后端一次性返回所有数据）。
5. 服务端状态同步：Mutation 与查询失效的组合拳
查询是读数据，Mutation 是写数据。写完之后要让读数据的查询重新同步，这是服务端状态管理的最后一个闭环。很多人写出了“死代码”，就是因为只用了useQuery没有配套useMutation的失效机制。
5.1 useMutation 的完整姿势
useMutation的用法和useQuery有些相近但本质不同。Mutation 没有查询键，因为它不管理可缓存的数据，它只管执行变更操作并暴露状态。
import { useMutation, useQueryClient } from '@tanstack/react-query' function CreateUserButton() { const queryClient = useQueryClient() const mutation = useMutation({ mutationFn: (newUser) => axios.post('/api/users', newUser), onSuccess: () => { queryClient.invalidateQueries({ queryKey: ['users', 'list'] }) }, onError: (error) => { message.error(error.response?.data?.message ?? '创建失败') } }) return ( <button onClick={() => mutation.mutate({ name: '张三' })} disabled={mutation.isPending} > {mutation.isPending ? '提交中...' : '新建用户'} </button> ) }mutation.mutate()触发变更，isPending表示变更进行中，可以用来禁用按钮防止重复提交。onSuccess里做查询失效，onError里做错误提示。这个模式已经覆盖了绝大部分表单提交流程。
5.2 乐观更新：让界面先响应，再纠正
有些对速度要求高的交互适合做乐观更新：先假设后端会成功，把 UI 改成目标状态，请求发出后在onError里回滚。
案例场景：用户给文章点赞。点赞按钮不应该转圈等后端返回，而是立刻变成已点赞状态。实现方式是用onMutate在请求发出前同步修改缓存：
const queryClient = useQueryClient() const likeMutation = useMutation({ mutationFn: () => likeArticle(articleId), onMutate: async () => { await queryClient.cancelQueries({ queryKey: ['article', articleId] }) const previousData = queryClient.getQueryData(['article', articleId]) queryClient.setQueryData(['article', articleId], (old) => ({ ...old, liked: true, likeCount: old.likeCount + 1, })) return { previousData } }, onError: (error, _, context) => { queryClient.setQueryData(['article', articleId], context.previousData) }, onSettled: () => { queryClient.invalidateQueries({ queryKey: ['article', articleId] }) } })这段代码有几个细节需要注意。首先在onMutate里调用了cancelQueries，目的是把正在进行的查询请求取消掉，避免在setQueryData改完缓存之后，旧的查询响应又回来覆盖掉最新缓存。其次，onMutate的返回值会被传给onError的第三个参数，我们在这里把旧的快照传回去，用于错误回滚。最后onSettled无论如何都会执行，在里面做一次失效重取，让后端真正的状态覆盖掉乐观结果。这一套流程下来，用户感知是即时的，数据一致性最终也能得到保证。
5.3 失效的粒度控制
invalidateQueries的queryKey支持模糊匹配前缀。比如queryClient.invalidateQueries({ queryKey: ['users'] })会失效所有以users开头的查询，包括['users', 'list', { page: 1 }]、['users', 'detail', 1]等所有相关查询。
这个特性在用户资料变更后特别有用，一次操作可以刷新跟用户相关的所有区块。但如果项目里有不同的功能模块共享了同一个users前缀，失效范围就会过大。建议设计查询键时，在前缀上再分一层业务域，比如['users', 'list']和['users', 'detail']，需要精确失效时就传完整键，需要模糊刷新时就传前缀。
6. 常见问题与排查技巧（实战踩坑记录）
再顺手的工具，用起来总会碰到一些诡异的坑。这节我整理几个在项目里真实遇到、排查起来比较费劲的问题，附上原因分析和解决办法，能帮你少走点弯路。
6.1 数据一直不更新，到底是不是缓存没失效
症状：调用了invalidateQueries，但界面上数据还是旧的。排查方向有两条。
先看查询键是否真的匹配。比如列表用的是['users', 'list', { page, pageSize }]，你失效时写的是invalidateQueries({ queryKey: ['users'] })，除非['users']是前者前缀，否则不会命中。查一下控制台里 TanStack Query DevTools 的缓存列表，一眼就能看出来失效操作是否匹配到了查询。
再看staleTime的设置。如果列表的staleTime设得很长，比如 5 分钟，invalidateQueries虽然会把查询标记为失效，但如果这个查询是 inactive 状态（没有组件在订阅），它不会立即重新执行，只有下次被挂载时才会发请求。这其实是设计行为，让后台悄悄刷新，不打扰用户。排查这类问题时，打开 DevTools 观察查询的状态颜色，绿色是新鲜、灰色是无效待刷新，状态一目了然。
| 现象 | 原因 | 解决办法 |
|---|---|---|
| 数据永远不变 | 查询键不匹配或 staleTime 过大 | 校准查询键、调整 staleTime |
| 期望刷新但没请求 | 查询处于 inactive 状态，无人订阅 | 挂载对应组件或手动 refetch |
| 请求发了但数据被覆盖 | 多个查询键指向同一字段 | 检查查询键哈希是否冲突 |
6.2 请求重复发送，尤其是 StrictMode 环境下
React 18 的 StrictMode 在开发环境下会故意挂载、卸载、再挂载组件，以帮助你发现副作用问题。TanStack Query 在挂载时会执行一次查询，卸载时清除订阅，再挂载时重新执行，所以你会看到两个重复请求。
这是开发模式下的正常行为，不是 bug。如果线上也出现重复请求，要检查是不是组件在渲染时调用了queryClient.refetchQueries之类的副作用，或者某个查询函数在渲染回调里被调用。把请求逻辑放在后面可以避免这种问题：优先用useQuery本身，而不是手动触发请求。同时，staleTime设置得合理一点，也能帮助减少重复请求。
6.3 查询取消与接口响应时间的对抗
TanStack Query 支持通过 AbortController 取消过时的查询。它的取消机制是：如果查询键变化导致旧查询被替换，且新查询已经发起，则旧查询会被标记为取消，对应的 AbortSignal 会触发 abort。
使用 axios 时，可以让查询函数接收signal参数并传入请求配置：
const { data } = useQuery({ queryKey: ['users', 'list', { page }], queryFn: ({ signal }) => axios.get('/api/users', { signal }), })这样做的好处是，用户快速翻页时，旧请求会被真实取消，而不是任由它跑完再丢弃。在列表加载大量数据的场景，取消效果非常明显，能减少网络带宽消耗和无效响应处理。
如果用的是 fetch，把signal传给fetch的第二个参数即可。注意，有些后端不支持主动取消请求，但前端的 AbortController 依然会忽略响应，达到同样的“不处理旧响应”的效果。
6.4 分页列表翻到下一页，旧数据还在界面上闪烁
这个问题通常发生在isLoading状态处理不当的时候。TanStack Query 中，切换到新查询键后，如果旧键的缓存存在，新键没有缓存，组件的isLoading可能是false（因为有旧数据在），但data却指向了新键的 undefined。UI 上就会闪过一个空白或者旧列表。
解决办法是区分isLoading（无任何缓存时加载中）和isFetching（重新加载中）。对于翻页场景，最佳做法是渲染时用isPlaceholderData来判断当前数据是否为占位数据：
const { data, isFetching, isPlaceholderData } = useQuery({ queryKey: ['users', 'list', { page }], queryFn: () => fetchUsers({ page }), placeholderData: keepPreviousData, })加上placeholderData: keepPreviousData后，切换查询键时，组件会保持展示上一页的数据作为占位，直到新数据返回。这样用户翻页时界面完全不会闪烁，顶多多等一两百毫秒。这是体验优化的一个关键细节，很多项目在初期没注意，后期被用户投诉翻页“闪一下”才来找解决方案。
6.5 表单联动导致的多个查询串行等待
有些页面有筛选联动，比如选完电商平台再选店铺，平台和店铺的选项数据分别来自不同的接口。新手容易写成在第一个useEffect里请求平台数据，拿到之后再请求店铺数据，结果两个请求天然串行，等待时间长了一倍。
优化方式是把两个请求都直接挂到页面的 query 上，店铺列表的查询仅在选中平台后才启用，虽然还是串行，但如果你把店铺的请求也设计成用enabled: !!selectedPlatform，就会发现 TanStack Query 的依赖查询模式和状态管理在联动场景下特别顺手。更好的是，如果店铺列表不依赖平台选择，完全可以直接并行发起。在真实项目里，这两个接口几乎总是有关联的——店铺是依据平台来选的。这一块没有银弹，关键在于别用useEffect手动控制发起请求的时机，让 TanStack Query 根据查询键和enabled自动编排。
7. 总结之外：排查实录与个人调优心得
能写 query 只是会用工具，能写好 query 才是对服务端状态管理的理解到位。最后一节，我分享几条我自己的经验总结，都是被真实项目毒打之后沉淀下来的东西。
7.1 查询键规范，决定项目的长期代码健康度
查询键不仅是缓存的地址，也是团队协作时的隐性接口。项目做大了以后，A 模块可能要失效 B 模块的查询，如果查询键没有规范，就得翻代码找键的拼写，效率很低。
我的做法是在项目里维护一个查询键常量文件。比如src/api/keys.ts，统一导出一系列带语义的函数，如下：
export const userKeys = { all: ['users'] as const, list: (filters: UserFilters) => [...userKeys.all, 'list', filters] as const, detail: (id: string) => [...userKeys.all, 'detail', id] as const, }这样其他模块只需要引用函数，不需要关心缓存地址的具体字符串。另外，用 TypeScript 的as const断言能保证关键字符串不被意外修改。一旦项目引入 TanStack Query，尽早建立查询键规范，比后期重构要省太多事了。
7.2 预设全局配置，减少重复代码
在创建 QueryClient 时，设置一套适合项目特性的全局默认值，能免去每个查询写重复参数。
const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 15 * 1000, gcTime: 10 * 60 * 1000, refetchOnWindowFocus: false, retry: (failureCount, error) => { const status = error?.response?.status if (status >= 400 && status < 500) return false return failureCount < 2 }, }, }, })系统默认的refetchOnWindowFocus为true，内部管理页面如果不需要这个特性可以关闭。staleTime用 15 秒到 30 秒通常是个不错的折中方案，既保证数据不会太旧，又避免切换 tab 或刷新页面时无意义的重复请求。这套全局配置确定后，单个查询里只需要覆盖少数例外情况，代码观感会清爽很多。
7.3 借助 DevTools 做实时诊断
TanStack Query 官方 DevTools 是排查问题的利器，可以直接在浏览器里查看所有缓存查询的键、状态、最后更新时间，可以手动触发刷新、删除缓存、修改 staleTime。我在排查问题时的标准操作是：先打开 DevTools 看缓存列表，确认查询是否存在以及状态是新鲜还是失效，然后根据状态判断是缓存命中问题还是查询触发问题，基本上一分钟就能定位到这层的问题。
DevTools 在开发环境默认启用，生产环境默认禁用，不会影响用户。把它加入项目几乎是零成本的投资，排查缓存问题能节省大量时间。
7.4 服务端状态与客户端状态要分开
这是最后一条，也是最重要的一条心得。TanStack Query 管的是服务端状态，全局表单输入、弹窗开合、UI 主题这类客户端状态，你应该继续用 useState、Zustand 或者 Context 管理。不要把从 useQuery 里拿到的 data 再复制一份存到全局 store 里，那样会破坏 TanStack Query 的订阅更新机制。组件里直接用 useQuery 拿到的 data 就能实时响应缓存变化，一旦你复制了一份到别处，缓存更新时那份复制品不会自动同步，于是你又得手动通知，最终方案越来越复杂。
我的习惯是：数据驱动视图时直接消费 useQuery 的返回值；只有页面模块间需要共享当前选中行之类的交互状态时，才用 Zustand 之类的客户端状态库。这个边界划清楚，整个项目的状态管理会异常清晰。
结尾
我在实际项目里把这套查询方案稳定跑了几年，最大的感受是，TanStack Query 真正帮你的是把“服务端数据”从组件生命周期里解放出来了。以前数据得跟着组件走，组件销毁数据就没了，重新进入页面又得重新拉；现在数据活在缓存里，它是全局共享的、有生命周期的，组件只是订阅者。这个心智转变一旦建立，写列表页、详情页、联动筛选就再也不是体力活了。
最后再分享一个小技巧：接口返回的响应如果有嵌套结构，建议在查询函数返回前做一次数据打平（normalize），比如把数组转成以 ID 为键的映射，再配合select选项做派生数据。这样列表渲染时查找单条数据的复杂度是 O(1)，也会让setQueryData做局部更新时省去遍历数组的麻烦。这个技巧在数据量大或者高频更新的项目里收益很明显，值得试一试。
