# 📡技能：tanstack-query-expert (v1.0.0) ## 执行摘要 TanStack Query v5 的高级服务器状态架构师 (2026)。专门从事反应式数据获取、高级缓存以及与 React 19 和 Next.js 16 的高性能集成。擅长消除瀑布、管理复杂的突变状态以及通过 Next.js“使用缓存”和部分预渲染 (PPR) 利用平台级缓存。 ** ** ## 📋 指挥礼仪 1. **架构选择**：确定数据提取是否应该在 RSC 中（通过 React 19 `use` hook + `"use cache"`）或在客户端（通过 TanStack Query）进行。 2. **Hydration Strategy** ：对于 SSR/PPR，始终在服务器上预取并使用“HydrationBoundary”来确保客户端数据的即时可用性。 3. **Mutation Tracking** ：使用 `useMutationState` 来处理全局加载/挂起状态，而无需进行 prop 钻取。 4. **验证**：使用 TanStack Query Devtools v5 审核查询状态、过时时间和缓存失效。 ** ** ## 🛠️ 强制性协议（2026 年标准） ### 1\. “对象语法”规则 TanStack Query v5 仅支持所有挂钩的基于对象的语法。 * **规则** ：切勿使用已弃用的位置参数语法（例如，`useQuery(key, fn)`）。 * **正确**：`useQuery({ queryKey: [...], queryFn: ... })`。 ### 2\. React 19 和 Next.js 16 集成 * **PPR First** ：在 `` 中使用 TanStack 查询包装客户端组件，以允许 Next.js 16 在提供静态 shell 的同时流式传输内容。 * **“使用缓存”指令**：对于服务器端预取，利用 Next.js 16 的“使用缓存”在平台级别缓存预取结果。 * **Action Mutations** ：对于简单形式的突变，更喜欢 React 19 Actions；使用 TanStack 查询突变进行复杂状态、乐观更新和后台重新获取。 ### 3\.缓存和性能强化 * **过时时间** ：默认为至少“5000”（5 秒）以防止过度重新获取。 * **GC Time** ：使用`gcTime`（从v5中的`cacheTime`重命名）来管理内存清理。 * **查询键**：始终使用稳定的、基于数组的查询键。将键视为数据的唯一标识符。 ** ** ## 🚀 展示，而不仅仅是讲述（实现模式） ### 快速入门：带有 Suspense 的现代查询 (React 19) “使用客户端”；从“@tanstack/react-query”导入{useSuspenseQuery}；从“@tanstack/react-query”导入{queryOptions}； // 模式：可重用查询选项导出 const userOptions = (id: string) => queryOptions({ 查询键：[“用户”，id]， queryFn: async () => { const res = wait fetch(`/api/users/${id}`); if (!res.ok) throw new Error("获取失败"); 返回 res.json(); }, staleTime: 1000 * 60 * 5, // 5 分钟 }); 导出函数 UserProfile({ id }: { id: string }) { // 通过 Suspense 保证数据可用性 const { 数据：用户 } = useSuspenseQuery(userOptions(id)); return

欢迎，{user.name}

; } ### 高级模式：全局突变跟踪从“@tanstack/react-query”导入{useMutationState}；函数待上传（）{ constendingVariables = useMutationState({ 过滤器：{ 状态：“待处理”，mutationKey：[“上传”] }，选择：（mutation）=>mutation.state.variables as { fileName: string }, }); 返回（

正在上传 {vars.fileName}...

）； } ** ** ## 🛡️ 禁止列表（反模式） 1. **不要**在 `useQuery` 中使用 `onSuccess`、`onError` 或 `onSettled`。它们在 v5 中被删除。使用“useEffect”或将逻辑移至“queryFn”。 2. **不要**忽略`isPending`。它在 v5 中替换了“isLoading”以表示“尚无数据”状态。 3. **不要**在没有“queryKey”的情况下使用“useQuery”。这是有效管理缓存的唯一方法。 4. **不要**忘记在服务器上`await` prefetchQuery。未等待的预取会导致水合不匹配。 5. **不要**将“enabled”与“useSuspenseQuery”一起使用。它与数据存在的保证不兼容。 ** ** ## 📂 渐进式披露（深入研究） * **[v5 迁移和重大更改]()**：安全地从 v4 迁移到 v5。 * **[Next.js 16 SSR& Hydration]()**：预取、“HydrationBoundary”和“使用缓存”。 * **[高级突变和乐观 UI]()**：useMutationState 和简化的 v5 模式。 * **[性能和无限查询]()**：maxPages 和双向分页。 ** ** ## 🛠️ 专用工具和脚本 * `scripts/audit-query-keys.ts`：检查非数组查询键或不稳定的键生成。 * `scripts/generate-query-hook.py`：v5 查询/突变对的样板生成器。 ** ** ## 🎓 学习资源 * [TanStack 查询文档]() * [TkDodo 的博客（维护者）]() * [React 19 数据获取指南]() ** ** _更新时间：2026 年 1 月 23 日 - 16:45_

Tanstack 查询专家

包含技能