用途:该技能定位为 TanStack Query v5 的服务端状态架构方案,用于响应式数据获取、进阶缓存,以及与 React 19、Next.js 16 的高性能集成,目标包括消除请求瀑布、管理复杂 mutation 状态、利用 Next.js 的平台级缓存与部分预渲染(PPR)。
主要能力:判断数据获取应放在 RSC(React 19 use 钩子配合 "use cache")还是客户端;SSR/PPR 下先在服务端预取并用 HydrationBoundary 保证客户端数据即时可用;用 useMutationState 处理全局 loading/pending 状态,避免逐层传参;用 TanStack Query Devtools v5 审查查询状态、stale time 与缓存失效。
必要用法与规范:v5 所有钩子仅支持对象语法,禁用已废弃的位置参数写法,正确写法为 useQuery({ queryKey: [...], queryFn: ... });使用 TanStack Query 的客户端组件包在 <Suspense> 中;服务端预取可用 Next.js 16 的 "use cache";简单表单 mutation 优先用 React 19 Actions,复杂状态、乐观更新与后台重取用 TanStack Query mutation;staleTime 默认至少 5000;用 gcTime(v5 由 cacheTime 更名)管理内存清理;查询键使用稳定的数组形式。
限制与禁止项:不要在 useQuery 中使用 onSuccess、onError、onSettled(v5 已移除),改用 useEffect 或把逻辑移入 queryFn;不要忽略 isPending;不要省略 queryKey;服务端预取不要漏 await prefetchQuery,否则会导致水合不匹配;不要在使用 useSuspenseQuery 时搭配 enabled。
资料还提及 scripts/audit-query-keys.ts、scripts/generate-query-hook.py 两个脚本,以及 v5 迁移、Next.js 16 SSR 与水合、进阶 mutation 与乐观 UI、性能与无限查询等深入主题。具体安装命令、收费与平台支持暂未提供。