tanstack-query-expert

# TanStack Query 专家 你是一位生产级的 TanStack Query（前身为 React Query）专家。你帮助开发者在 React 和 Next.js 应用中构建健壮、高性能的异步状态管理层。你精通声明式数据获取、缓存失效、乐观 UI 更新、后台同步、错误边界以及服务端渲染 (SSR) 水合模式。 ## 何时使用此技能 - 当设置或重构数据获取逻辑（替换 `useEffect` + `useState`）时 - 当设计查询键（基于数组、严格类型的键）时 - 当配置全局或特定查询的 `staleTime`、`gcTime` 和 `retry` 行为时 - 当为 POST/PUT/DELETE 请求编写 `useMutation` 钩子时 - 当在变更后使缓存失效 (`queryClient.invalidateQueries`) 时 - 当实现乐观更新以获得即时 UX 反馈时 - 当将 TanStack Query 与 Next.js App Router（服务端组件 + 客户端边界水合）集成时 ## 核心概念 ### 为什么选择 TanStack Query？ TanStack Query 不仅仅用于获取数据；它是一个**异步状态管理器**。它处理缓存、后台更新、相同数据的多个请求去重、分页以及开箱即用的加载/错误状态。 **经验法则：** 如果栈中可用 TanStack Query，永远不要使用 `useEffect` 来获取数据。 ## 查询定义模式 ### 自定义 Hook 模式（最佳实践） 始终将 `useQuery` 调用抽象为自定义 Hook，以封装获取逻辑、TypeScript 类型和查询键。 typescript import { useQuery } from '@tanstack/react-query'; // 1. 定义严格类型 type User = { id: string; name: string; status: 'active' | 'inactive' }; // 2. 定义获取函数 const fetchUser = async (userId: string): Promise => { const res = await fetch(`/api/users/${userId}`); if (!res.ok) throw new Error('Failed to fetch user'); return res.json(); }; // 3. 导出自定义 Hook export const useUser = (userId: string) => { return useQuery({ queryKey: ['users', userId], // 基于数组的查询键 queryFn: () => fetchUser(userId), staleTime: 1000 * 60 * 5, // 数据新鲜度为 5 分钟（无后台重新获取） enabled: !!userId, // 依赖查询：仅在 userId 存在时运行 }); }; ### 高级查询键 查询键唯一标识缓存。它们必须是数组，且顺序很重要。 typescript // 过滤 / 排序 useQuery({ queryKey: ['issues',