TanStack Query 用法简单说明

TanStack Query（前身为 React Query） 是 React 中用于管理异步服务端状态（Server State）的利器。它能自动帮你处理数据获取、缓存、背景更新、防抖与重复请求合并等复杂逻辑。

要掌握它的基本用法，只需要理解三个核心概念：Queries（数据查询）、Mutations（数据变更） 和 Query Invalidation（缓存失效/重新拉取）。

1. 基础配置 (Setup)

在应用根节点，需要使用 QueryClientProvider 包裹你的组件：

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

// 1. 创建 Client 实例
const queryClient = new QueryClient()

function App() {
  return (
    // 2. 将 client 提供给整个应用
    <QueryClientProvider client={queryClient}>
      <Todos />
    </QueryClientProvider>
  )
}

2. 核心概念与用法

① 查询数据：useQuery

用于获取 (GET) 数据。需要传入两个核心参数：

queryKey: 数组形式的唯一定时标识符（缓存 key）。当 key 改变时，查询会自动重新触发。

queryFn: 返回 Promise 的异步请求函数。

import { useQuery } from '@tanstack/react-query'
import { getTodos } from './api'

function Todos() {
  const { data, isLoading, isError, error } = useQuery({
    queryKey: ['todos'],
    queryFn: getTodos,
  })

  if (isLoading) return <div>加载中...</div>
  if (isError) return <div>发生错误: {error.message}</div>

  return (
    <ul>
      {data?.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}

② 修改数据：useMutation

用于新建、更新或删除 (POST/PUT/DELETE) 数据。

import { useMutation } from '@tanstack/react-query'
import { postTodo } from './api'

function AddTodo() {
  const mutation = useMutation({
    mutationFn: postTodo,
    onSuccess: () => {
      console.log('添加成功！')
    },
  })

  return (
    <button
      onClick={() => {
        mutation.mutate({ title: '写代码' })
      }}
    >
      {mutation.isPending ? '提交中...' : '添加 Todo'}
    </button>
  )
}

③ 刷新/使缓存失效：useQueryClient

当通过 mutation 修改了服务器数据后，本地缓存的数据就“过时”了。此时可以通过 invalidateQueries 通知指定的 queryKey 重新拉取最新数据。

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'

function TodosApp() {
  // 获取 queryClient 实例
  const queryClient = useQueryClient()

  // 查询列表
  const { data: todos } = useQuery({ 
    queryKey: ['todos'], 
    queryFn: getTodos 
  })

  // 变更操作：添加 Todo
  const mutation = useMutation({
    mutationFn: postTodo,
    onSuccess: () => {
      // 成功后使 ['todos'] 缓存失效，让 React Query 自动重新获取最新数据
      queryClient.invalidateQueries({ queryKey: ['todos'] })
    },
  })

  return (
    <div>
      <ul>
        {todos?.map(todo => <li key={todo.id}>{todo.title}</li>)}
      </ul>
      <button onClick={() => mutation.mutate({ title: '新任务' })}>
        添加任务
      </button>
    </div>
  )
}

3. React Query 带来的优势

**自动缓存与去重：**相同的请求在同一时间内不会重复触发，且数据会自动存入内存缓存。

**后台静默更新 (Stale-While-Revalidate)：**即使页面有缓存数据，它也会在后台重新拉取新数据，保证用户界面既响应迅速，内容又不会落后。

**强大的状态追踪：**内置 isLoading、isPending、isError、isSuccess 等状态标志，无需手写大量的 try-catch 和 useState。