# npm
npm install @tanstack/react-query
 
# pnpm
pnpm add @tanstack/react-query
 
# yarn
yarn add @tanstack/react-query

// main.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 
// 创建 QueryClient 实例
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 分钟内数据视为新鲜
      retry: 1,                  // 失败重试 1 次
      refetchOnWindowFocus: true // 窗口聚焦时重新获取
    }
  }
})
 
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
 
// 数据获取
function UserList() {
  const { data, isLoading, error, refetch } = useQuery({
    queryKey: ['users'],
    queryFn: async () => {
      const response = await fetch('/api/users')
      if (!response.ok) throw new Error('Network error')
      return response.json()
    }
  })
 
  if (isLoading) return <div>加载中...</div>
  if (error) return <div>错误: {error.message}</div>
 
  return (
    <div>
      <h1>用户列表</h1>
      <button onClick={() => refetch()}>刷新</button>
      <ul>
        {data.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  )
}
 
// 数据变更
function CreateUser() {
  const queryClient = useQueryClient()
 
  const mutation = useMutation({
    mutationFn: (newUser) => fetch('/api/users', {
      method: 'POST',
      body: JSON.stringify(newUser)
    }),
    onSuccess: () => {
      // 成功后使缓存失效并重新获取
      queryClient.invalidateQueries({ queryKey: ['users'] })
    }
  })
 
  return (
    <form onSubmit={(e) => {
      e.preventDefault()
      mutation.mutate({ name: '新用户' })
    }}>
      <button type="submit">创建用户</button>
      {mutation.isPending && <span>提交中...</span>}
    </form>
  )
}

const mutation = useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    await queryClient.cancelQueries({ queryKey: ['todos'] })
    const previous = queryClient.getQueryData(['todos'])
    queryClient.setQueryData(['todos'], old => [...old, newTodo])
    return { previous }
  },
  onError: (err, newTodo, context) => {
    queryClient.setQueryData(['todos'], context.previous)
  },
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['todos'] })
  }
})

interface User {
  id: string
  name: string
  email: string
}
 
// 自动推导 data 类型为 User | undefined
const { data } = useQuery({
  queryKey: ['users', userId],
  queryFn: (): Promise<User> => fetchUser(userId)
})
 
// data 的类型被精确推导
if (data) {
  console.log(data.name) // 类型安全
}

pnpm add -D @tanstack/eslint-plugin-query

{
  "plugins": ["@tanstack/query"],
  "rules": {
    "@tanstack/query/exhaustive-deps": "error"
  }
}

import { render, screen, waitFor } from '@testing-library/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { UserList } from './UserList'
 
function createWrapper() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: { retry: false }
    }
  })
  return function Wrapper({ children }) {
    return (
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    )
  }
}
 
test('显示用户列表', async () => {
  render(<UserList />, { wrapper: createWrapper() })
  await waitFor(() => {
    expect(screen.getByText('用户列表')).toBeInTheDocument()
  })
})

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5,   // 5 分钟新鲜期
      gcTime: 1000 * 60 * 30,     // 30 分钟缓存保留
      retry: 2,                    // 失败重试 2 次
      retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000),
      refetchOnWindowFocus: true,
      refetchOnReconnect: true,
      networkMode: 'online'        // 'online' | 'always' | 'offlineFirst'
    },
    mutations: {
      retry: 0                     // Mutation 默认不重试
    }
  }
})

// 推荐：使用数组 + 对象，确保唯一性
useQuery({ queryKey: ['users', { status: 'active', page: 1 }], queryFn: ... })
useQuery({ queryKey: ['users', userId, 'posts'], queryFn: ... })
 
// 避免：字符串拼接，容易冲突
useQuery({ queryKey: `users-${userId}`, queryFn: ... })

// 静态数据：长 staleTime
useQuery({
  queryKey: ['config'],
  queryFn: fetchConfig,
  staleTime: 1000 * 60 * 60 * 24 // 24 小时
})
 
// 实时数据：短 staleTime + refetchInterval
useQuery({
  queryKey: ['stock', symbol],
  queryFn: fetchStockPrice,
  staleTime: 1000 * 5,
  refetchInterval: 1000 * 10 // 每 10 秒轮询
})

const mutation = useMutation({
  mutationFn: createUser,
  onSuccess: (data) => {
    toast.success('用户创建成功')
    queryClient.invalidateQueries({ queryKey: ['users'] })
    queryClient.setQueryData(['users', data.id], data) // 乐观更新缓存
  },
  onError: (error) => {
    toast.error(`创建失败: ${error.message}`)
    // 不需要手动回滚，Query 会自动重新获取
  }
})

// 并行获取多个相关数据
const queries = useQueries({
  queries: [
    { queryKey: ['user', id], queryFn: fetchUser, enabled: !!id },
    { queryKey: ['user', id, 'posts'], queryFn: fetchUserPosts, enabled: !!id },
    { queryKey: ['user', id, 'settings'], queryFn: fetchUserSettings, enabled: !!id }
  ]
})
 
const allLoaded = queries.every(q => !q.isLoading)

// Server Component：服务端获取初始数据
async function Page() {
  const initialData = await fetchData()
  return <ClientComponent initialData={initialData} />
}
 
// Client Component：接管后续数据更新
'use client'
function ClientComponent({ initialData }) {
  const { data } = useQuery({
    queryKey: ['data'],
    queryFn: fetchData,
    initialData
  })
  // ...
}

// 精准失效：只失效相关查询
queryClient.invalidateQueries({ queryKey: ['users', userId] })
 
// 前缀匹配：失效所有用户相关查询
queryClient.invalidateQueries({ queryKey: ['users'] })
 
// 精确匹配：只失效完全匹配的查询
queryClient.invalidateQueries({ queryKey: ['users'], exact: true })