React: TanStack Query（React Query）

// 手动管理缓存 — 每个组件都要写类似的逻辑
function Dashboard() {
  const [data, setData] = useState(null)
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    fetch('/api/stats').then(res => res.json())
      .then(d => { setData(d); setLoading(false) })
      .catch(e => { setLoading(false) })
  }, [])

  // 问题 1：切到其他页面再回来 → 重新请求（浪费！）
  // 问题 2：如果有另一个组件也需要同样数据 → 重复请求
  // 问题 3：数据不会自动刷新，用户看到的可能是几分钟前的数据
}

npm install @tanstack/react-query

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

// 创建 QueryClient（通常在 app 入口处）
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30 * 1000,      // 默认 30 秒内数据视为"新鲜"
      cacheTime: 5 * 60 * 1000,  // 缓存保留 5 分钟
      retry: 3,                  // 失败重试 3 次
      refetchOnWindowFocus: true, // 窗口切换回前台时重取
    }
  }
})

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

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

// 封装的 API 函数
async function fetchDashboardStats() {
  const response = await fetch('/api/dashboard/stats')
  if (!response.ok) throw new Error('获取统计数据失败')
  return response.json()
}

function Dashboard() {
  // useQuery 一行代码代替了 useState + useEffect + 手动缓存
  const {
    data: stats,        // 响应数据
    isLoading,          // 首次加载中（无缓存时）
    isFetching,         // 是否正在请求（包括后台重取）
    error,              // 错误对象
    refetch             // 手动触发重取
  } = useQuery({
    queryKey: ['dashboardStats'],   // 唯一标识，用于缓存匹配
    queryFn: fetchDashboardStats,   // 数据获取函数
    staleTime: 30 * 1000,           // 30 秒内不重新请求
    retry: 3,                       // 失败重试 3 次
  })

  if (isLoading) return <DashboardSkeleton />
  if (error) return <ErrorPanel message={error.message} onRetry={refetch} />

  return (
    <div className="dashboard">
      <StatCard title="用户总数" value={stats.users} />
      <StatCard title="订单总数" value={stats.orders} />
      <StatCard title="总收入" value={`$${stats.revenue}`} />
    </div>
  )
}

// 侧边栏也显示用户数量 — 使用相同的 queryKey，不会重复请求！
function Sidebar() {
  const { data: stats } = useQuery({
    queryKey: ['dashboardStats'],
    queryFn: fetchDashboardStats,
    staleTime: 30 * 1000,
  })

  return (
    <aside>
      <p>在线用户：{stats?.onlineUsers ?? '...'}</p>
    </aside>
  )
}

function ProductDetail({ productId }) {
  const { data, isLoading, error } = useQuery({
    queryKey: ['product', productId],    // queryKey 包含参数
    queryFn: async () => {
      const res = await fetch(`/api/products/${productId}`)
      if (!res.ok) throw new Error('商品不存在')
      return res.json()
    },
    enabled: !!productId,    // productId 为空时不发请求
    staleTime: 60 * 1000,
  })

  if (isLoading) return <p>加载商品详情...</p>
  if (error) return <p>错误：{error.message}</p>

  return (
    <div>
      <h2>{data.name}</h2>
      <p className="price">${data.price}</p>
      <p>{data.description}</p>
    </div>
  )
}

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

// 商品列表查询
function useProducts() {
  return useQuery({
    queryKey: ['products'],
    queryFn: async () => {
      const res = await fetch('/api/products')
      return res.json()
    }
  })
}

function ProductManager() {
  const queryClient = useQueryClient()

  // 添加商品的 mutation
  const addProductMutation = useMutation({
    mutationFn: async (newProduct) => {
      const res = await fetch('/api/products', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(newProduct)
      })
      if (!res.ok) throw new Error('添加失败')
      return res.json()
    },
    // 成功后的操作：使商品列表缓存失效，触发重新请求
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['products'] })
      // 可选：同时显示成功提示
      alert('商品添加成功！')
    },
    // 失败处理
    onError: (error) => {
      alert(`添加失败：${error.message}`)
    }
  })

  // 数据
  const { data: products, isLoading } = useProducts()

  // 表单提交
  function handleSubmit(event) {
    event.preventDefault()
    const formData = new FormData(event.target)
    const newProduct = {
      name: formData.get('name'),
      price: Number(formData.get('price'))
    }
    addProductMutation.mutate(newProduct)
    event.target.reset()
  }

  return (
    <div>
      <h2>商品管理</h2>

      <form onSubmit={handleSubmit}>
        <input name="name" placeholder="商品名称" required />
        <input name="price" type="number" placeholder="价格" required />
        <button type="submit" disabled={addProductMutation.isLoading}>
          {addProductMutation.isLoading ? '提交中...' : '添加商品'}
        </button>
      </form>

      {addProductMutation.isError && (
        <p className="error">提交失败：{addProductMutation.error.message}</p>
      )}

      <hr />

      <h3>商品列表</h3>
      {isLoading && <p>加载中...</p>}
      {products && (
        <ul>
          {products.map(p => (
            <li key={p.id}>{p.name} — ${p.price}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

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

// 获取待办列表
function useTodos() {
  return useQuery({
    queryKey: ['todos'],
    queryFn: async () => {
      const res = await fetch('/api/todos')
      return res.json()
    }
  })
}

function TodoList() {
  const queryClient = useQueryClient()
  const { data: todos } = useTodos()

  // 切换完成状态 — 使用乐观更新
  const toggleMutation = useMutation({
    // 实际的 API 请求
    mutationFn: async ({ id, done }) => {
      const res = await fetch(`/api/todos/${id}`, {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ done })
      })
      if (!res.ok) throw new Error('更新失败')
      return res.json()
    },

    // ===== 乐观更新开始 =====
    onMutate: async ({ id, done }) => {
      // 1. 取消所有正在进行的 todos 查询（避免覆盖乐观更新）
      await queryClient.cancelQueries({ queryKey: ['todos'] })

      // 2. 保存当前缓存数据，用于失败时回滚
      const previousTodos = queryClient.getQueryData(['todos'])

      // 3. 立即更新缓存
      queryClient.setQueryData(['todos'], (old) =>
        old.map(todo =>
          todo.id === id ? { ...todo, done } : todo
        )
      )

      // 4. 返回旧数据用于回滚
      return { previousTodos }
    },
    // ===== 乐观更新结束 =====

    // 失败时回滚
    onError: (err, variables, context) => {
      if (context?.previousTodos) {
        queryClient.setQueryData(['todos'], context.previousTodos)
      }
    },

    // 无论成功还是失败，最终重新请求确保与服务端同步
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] })
    }
  })

  return (
    <ul>
      {todos?.map(todo => (
        <li key={todo.id} style={{ opacity: toggleMutation.isLoading ? 0.7 : 1 }}>
          <input
            type="checkbox"
            checked={todo.done}
            onChange={() => toggleMutation.mutate({ id: todo.id, done: !todo.done })}
          />
          <span style={{ textDecoration: todo.done ? 'line-through' : 'none' }}>
            {todo.title}
          </span>
        </li>
      ))}
    </ul>
  )
}

npm install @tanstack/react-query-devtools

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
      {/* 只在开发环境显示 DevTools */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

import { queryClient } from './queryClient'

// 1. 使缓存失效（触发重新请求）
queryClient.invalidateQueries({ queryKey: ['products'] })

// 2. 清除所有缓存（用户登出时）
queryClient.clear()

// 3. 设置默认选项（全局修改 staleTime）
queryClient.setDefaultOptions({
  queries: { staleTime: 60 * 1000 }
})

// 4. 获取缓存数据（不触发请求）
const cachedData = queryClient.getQueryData(['products'])

// 5. 预取数据（用户 hover 到链接时提前加载）
queryClient.prefetchQuery({
  queryKey: ['product', '42'],
  queryFn: () => fetchProduct('42')
})
// 用户点击链接后，数据已经在缓存中，瞬间渲染

// 6. 取消正在进行的查询
queryClient.cancelQueries({ queryKey: ['product', '42'] })

// 全局默认：30 秒新鲜期
const queryClient = new QueryClient({
  defaultOptions: {
    queries: { staleTime: 30 * 1000, retry: 3 }
  }
})

// 某个查询覆盖：数据几乎不变，新鲜期设为 10 分钟
function useProductCategories() {
  return useQuery({
    queryKey: ['categories'],
    queryFn: fetchCategories,
    staleTime: 10 * 60 * 1000,  // 10 分钟内不重取
  })
}

// 另一个查询覆盖：实时性要求高，禁用缓存
function useRealtimeNotifications() {
  return useQuery({
    queryKey: ['notifications'],
    queryFn: fetchNotifications,
    staleTime: 0,               // 数据立刻过期
    refetchInterval: 30 * 1000, // 每 30 秒自动轮询
  })
}