跳到主要内容

基础概念

TanStack Query 最重要的不是 API 数量，而是先分清服务端状态和本地 UI 状态。

服务端状态是什么​

典型例子：

  • 用户详情
  • 列表数据
  • 权限信息
  • 配置项
  • 分页结果

这类数据有几个共同点：

  • 来自服务端
  • 会过期
  • 多个页面可能共享
  • 很容易遇到重复请求、缓存失效和刷新同步问题

TanStack Query 就是为这类数据准备的。

最核心的几个概念​

Query​

负责取数据。

useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

Mutation​

负责改数据。

useMutation({
  mutationFn: createTodo,
})

Query Key​

queryKey 是缓存定位的核心。

['todo', todoId]

它表面上像一个“名字”，实际决定了缓存分片、失效范围和重取行为。

staleTime​

数据多久算旧。

gcTime / cacheTime​

缓存多久被清走。不同版本文档里可能会看到 cacheTime 这个旧名字，阅读时要留意。

invalidateQueries​

主动让查询失效。

这是最常见的“改完数据，通知列表重取”的做法。

一个最基础的初始化​

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60,
      retry: 1,
      refetchOnWindowFocus: false,
    },
  },
})

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Root />
    </QueryClientProvider>
  )
}

什么时候它最值钱​

  • 列表和详情页共用数据
  • 表单提交后要刷新列表
  • 分页、筛选、搜索很多
  • 页面切换频繁，不想每次都重新拉一遍
  • 多处都依赖同一份服务端状态

不要拿它去做什么​

  • 弹窗开关
  • Tab 激活态
  • 表单输入过程状态
  • 拖拽中间状态

这些更适合本地状态管理。