TanStack Query Pro 使用指南：Next.js 16 数据获取、缓存与 SSR 优化 | SkillsMDTanStack Query Pro 使用指南：Next.js 16 数据获取、缓存与 SSR 优化
tanstack-query-pro by clownnvd/claude-code-skills
npx skills add https://github.com/clownnvd/claude-code-skills --skill tanstack-query-pro🇨🇳中文介绍
TanStack Query Pro -- 适用于 Next.js 16 的数据获取
使用时机
当提及以下任何内容时触发：tanstack query, react query, useQuery, useMutation, useSuspenseQuery, prefetch, dehydrate, HydrationBoundary, cache invalidation, optimistic updates, infinite scroll, staleTime, gcTime。
参考文件
根据用户需求加载相关参考文件：
| 文件 | 描述 |
|---|
references/setup.md | 版本兼容性 (TQ v5.90+ / React 19 / Next.js 16)，v4 到 v5 的重大变更 (14 项)，迁移代码修改工具，安装，使用 useState 模式的 QueryClientProvider，DevTools 设置 |
references/ssr-patterns.md | 3 种 SSR 方法：Prefetch+Dehydrate (推荐)，StreamedHydration，Streaming Prefetch (v5.40+)。使用时机决策表 |
references/queries.md | useQuery, useSuspenseQuery, queryOptions 辅助函数, skipToken, 查询键工厂, 并行查询, 依赖查询 |
|
🇺🇸English
TanStack Query Pro -- Data Fetching for Next.js 16
When to Use
Trigger on any mention of: tanstack query, react query, useQuery, useMutation, useSuspenseQuery, prefetch, dehydrate, HydrationBoundary, cache invalidation, optimistic updates, infinite scroll, staleTime, gcTime.
Reference Files
Load the relevant reference file(s) based on what the user needs:
| File | Description |
|---|
references/setup.md | Version compatibility (TQ v5.90+ / React 19 / Next.js 16), v4-to-v5 breaking changes (14 entries), migration codemod, installation, QueryClientProvider with useState pattern, DevTools setup |
references/ssr-patterns.md | 3 SSR approaches: Prefetch+Dehydrate (recommended), StreamedHydration, Streaming Prefetch (v5.40+). When-to-use decision table |
references/queries.md | useQuery, useSuspenseQuery, queryOptions helper, skipToken, query key factory, parallel queries, dependent queries |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者，精准高效
references/mutations.md
| useMutation, mutate 与 mutateAsync 对比, 乐观更新 (基于 UI 和基于缓存), 失效策略 (5 种方法) |
references/infinite-queries.md | useInfiniteQuery, Intersection Observer 自动加载, 传统页码分页, keepPreviousData |
references/caching.md | 按数据类型划分的 staleTime/gcTime 策略, 全局默认值, 缓存生命周期图 (FRESH -> STALE -> INACTIVE -> GC) |
references/performance.md | select 转换, placeholderData, 悬停/焦点预取, 结构共享, 使用 AbortSignal 取消查询 |
references/typescript.md | 类型推断模式, 自定义错误类型, 用于类型安全共享的 queryOptions, skipToken 条件查询, 变更类型安全 |
references/testing.md | 测试包装器/工具, 用于钩子的 renderHook, 变更测试, 使用 renderWithQuery 进行组件测试 |
references/errors.md | 18 个已记录的错误 (TQ-001 到 TQ-018)，包含确切消息、原因和修复方法 |
references/cviet-patterns.md | CViet 项目设置 (原样), 扩展的查询键工厂, AI 增强缓存, 仪表板 SSR 预取, 带防抖的 CV 自动保存, 账单/计划钩子 |
references/quick-reference.md | 查询状态标志表, 钩子快速参考, QueryClient 方法, 常见导入模式, 所有来源 |
错误快速查询
| ID | 错误 | 修复方法 |
|---|
| TQ-001 | 未设置 QueryClient | 用 QueryClientProvider 包装，使用 useState 创建客户端 |
| TQ-002 | 缺少 queryFn | 始终为 useQuery 提供 queryFn |
| TQ-003 | 水合不匹配 | 使用 dehydrate 确保服务器/客户端数据相同 |
| TQ-004 | 查询数据未定义 | queryFn 必须返回值，检查 res.ok 并抛出错误 |
| TQ-005 | 变更后数据过时 | queryClient.invalidateQueries({ queryKey }) |
| TQ-006 | 无限重新渲染 | 将 queryFn 移到组件外，使用稳定的 queryKey |
| TQ-007 | infinite 中的 undefined.length | 为 useQuery 和 useInfiniteQuery 使用不同的键 |
| TQ-008 | 导航时数据消失 | 在 useState 中创建 QueryClient，提高 gcTime |
| TQ-009 | gcTime 0 水合错误 | 至少使用 gcTime: 2000 |
| TQ-010 | fetch 在 4xx/5xx 时不抛出错误 | 使用自定义 fetch 包装器，在错误状态时抛出 |
| TQ-011 | QueryKey 类型错误 | 在查询键数组上使用 as const |
| TQ-012 | 渲染了更多钩子 | 使用 enabled 或 skipToken，切勿使用条件钩子 |
| TQ-013 | 重新获取覆盖了乐观更新 | 在设置缓存前，在 onMutate 中取消查询 |
| TQ-014 | Suspense 水合错误 | 在服务器上预取或使用 ReactQueryStreamedHydration |
| TQ-015 | 模块级 QueryClient | 在 useState 回调中创建，而非模块作用域 |
| TQ-016 | 生产环境中缺少 DevTools | 有意为之；如需使用，请从 devtools/production 导入 |
| TQ-017 | isLoading 始终为 false | v5 中已重命名：改用 isPending |
| TQ-018 | cacheTime 无效 | v5 中已重命名：改用 gcTime |
关键模式
SSR 预取 (推荐)
// 服务器组件
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
export default async function DashboardPage() {
const queryClient = new QueryClient()
await queryClient.prefetchQuery({ queryKey: ['cvs'], queryFn: fetchCVs })
return (
<HydrationBoundary state={dehydrate(queryClient)}>
<CVList />
</HydrationBoundary>
)
}
查询键工厂
export const cvKeys = {
all: ['cvs'] as const,
lists: () => [...cvKeys.all, 'list'] as const,
detail: (id: string) => [...cvKeys.all, 'detail', id] as const,
}
乐观更新 (基于缓存)
onMutate: async (newData) => {
await queryClient.cancelQueries({ queryKey: ['cvs'] })
const previous = queryClient.getQueryData(['cvs'])
queryClient.setQueryData(['cvs'], (old) => /* 更新 */)
return { previous }
},
onError: (err, vars, ctx) => queryClient.setQueryData(['cvs'], ctx.previous),
onSettled: () => queryClient.invalidateQueries({ queryKey: ['cvs'] }),
references/mutations.md | useMutation, mutate vs mutateAsync, optimistic updates (UI-based and cache-based), invalidation strategies (5 methods) |
references/infinite-queries.md | useInfiniteQuery, Intersection Observer auto-load, traditional page-number pagination, keepPreviousData |
references/caching.md | staleTime/gcTime strategies by data type, global defaults, cache lifecycle diagram (FRESH -> STALE -> INACTIVE -> GC) |
references/performance.md | select transforms, placeholderData, hover/focus prefetching, structural sharing, query cancellation with AbortSignal |
references/typescript.md | Type inference patterns, custom error types, queryOptions for type-safe sharing, skipToken conditional queries, mutation type safety |
references/testing.md | Test wrapper/utilities, renderHook for hooks, mutation testing, component testing with renderWithQuery |
references/errors.md | 18 documented errors (TQ-001 through TQ-018) with exact messages, causes, and fixes |
references/cviet-patterns.md | CViet project setup (as-is), expanded query key factory, AI enhancement caching, dashboard SSR prefetch, CV auto-save with debounce, billing/plan hooks |
references/quick-reference.md | Query status flags table, hook quick reference, QueryClient methods, common import patterns, all sources |
Error Quick Lookup
| ID | Error | Fix |
|---|
| TQ-001 | No QueryClient set | Wrap in QueryClientProvider, use useState for client |
| TQ-002 | Missing queryFn | Always provide queryFn to useQuery |
| TQ-003 | Hydration mismatch | Ensure same data on server/client with dehydrate |
| TQ-004 | Query data undefined | queryFn must return a value, check res.ok and throw |
| TQ-005 | Stale data after mutation | queryClient.invalidateQueries({ queryKey }) |
| TQ-006 | Infinite re-renders | Move queryFn outside component, stable queryKey |
| TQ-007 | undefined.length in infinite | Use distinct keys for useQuery vs useInfiniteQuery |
| TQ-008 | Data disappears on nav | Create QueryClient in useState, raise gcTime |
| TQ-009 | gcTime 0 hydration error | Use gcTime: 2000 minimum |
| TQ-010 | fetch no throw on 4xx/5xx | Custom fetch wrapper that throws on error status |
| TQ-011 | QueryKey type error | Use as const on query key arrays |
| TQ-012 | Rendered more hooks | Use enabled or skipToken, never conditional hooks |
| TQ-013 | Refetch overwrites optimistic | Cancel queries in onMutate before setting cache |
| TQ-014 | Suspense hydration error | Prefetch on server or use ReactQueryStreamedHydration |
| TQ-015 | Module-level QueryClient | Create inside useState callback, not module scope |
| TQ-016 | DevTools missing in prod | Intentional; import from devtools/production if needed |
| TQ-017 | isLoading always false | Renamed in v5: use isPending instead |
| TQ-018 | cacheTime not valid | Renamed in v5: use gcTime instead |
Key Patterns
SSR Prefetch (Recommended)
// Server Component
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
export default async function DashboardPage() {
const queryClient = new QueryClient()
await queryClient.prefetchQuery({ queryKey: ['cvs'], queryFn: fetchCVs })
return (
<HydrationBoundary state={dehydrate(queryClient)}>
<CVList />
</HydrationBoundary>
)
}
Query Key Factory
export const cvKeys = {
all: ['cvs'] as const,
lists: () => [...cvKeys.all, 'list'] as const,
detail: (id: string) => [...cvKeys.all, 'detail', id] as const,
}
Optimistic Update (Cache-Based)
onMutate: async (newData) => {
await queryClient.cancelQueries({ queryKey: ['cvs'] })
const previous = queryClient.getQueryData(['cvs'])
queryClient.setQueryData(['cvs'], (old) => /* update */)
return { previous }
},
onError: (err, vars, ctx) => queryClient.setQueryData(['cvs'], ctx.previous),
onSettled: () => queryClient.invalidateQueries({ queryKey: ['cvs'] }),
Flutter应用架构设计指南：分层结构、数据层实现与最佳实践
4,000 周安装
