TanStack Query

TanStack Query 是什么

TanStack Query（原名 React Query）是一个用于 异步状态管理 的库，专注于「服务端状态」：从接口取回的数据、缓存、失效、重取与同步。它不绑定具体请求库，REST、GraphQL、任意 Promise 都能接入。

同一套核心逻辑通过官方适配覆盖多个框架：

• React Query
• Vue Query
• Svelte Query
• Solid Query

核心能力

• 请求与缓存：自动缓存查询结果，按 key 管理数据
• 重取与失效：窗口聚焦、网络重连、手动失效等触发更新
• 分页与无限滚动：内置分页与无限加载辅助 API
• 变更提交（Mutations）：提交后自动失效相关查询，支持乐观更新与回滚
• 依赖查询与预取：按条件串行请求，提前预取下一页数据
• 请求取消与 Suspense：支持中止请求，React 下可配合 Suspense

使用示意

以 React 为例，通常先创建 QueryClient 并在应用根部提供 Provider，再用 hook 声明式地取数：

const { data, isLoading, error } = useQuery({
  queryKey: ['todos'],
  queryFn: () => fetch('/api/todos').then((r) => r.json()),
})

提交数据时使用 mutation，并在成功后让相关查询失效，从而触发自动刷新：

const mutation = useMutation({
  mutationFn: (todo) => postTodo(todo),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})

具体安装方式与各框架的接入细节，请以官方文档为准。

适合谁

• 前端项目中接口调用分散、loading/error 状态重复代码多的团队
• 需要分页、无限滚动、后台静默更新的数据密集型页面
• 使用 TypeScript、希望获得良好类型推导的中大型项目

注意事项

TanStack Query 管理的是服务端状态，客户端的 UI 状态（弹窗开关、表单草稿等）仍建议交给专门的状态方案。默认的窗口聚焦重取等行为，也应根据业务场景调整 staleTime 等参数。