tanstack-query

用途

TanStack Query Best Practices 是一份面向 TanStack Query v5 应用的性能优化指南，包含 8 个类别、共 41 条规则，按影响程度划分优先级，用于指导自动化重构与代码生成。

适用时机

在以下情况参考这些准则：

编写新的查询、变更（mutation）或数据获取逻辑
实现缓存策略（staleTime、gcTime）
审查代码中的性能问题或请求瀑布
重构现有的 TanStack Query 代码
实现无限查询、Suspense 或乐观更新

规则类别与优先级

优先级	类别	影响	前缀
1	Query Key Structure（查询键结构）	CRITICAL	tquery-
2	Caching Configuration（缓存配置）	CRITICAL	cache-
3	Mutation Patterns（变更模式）	HIGH	mutation-
4	Prefetching & Waterfalls（预取与请求瀑布）	HIGH	prefetch-
5	Infinite Queries（无限查询）	MEDIUM	infinite-
6	Suspense Integration（Suspense 集成）	MEDIUM	suspense-
7	Error & Retry Handling（错误与重试处理）	MEDIUM	error-
8	Render Optimization（渲染优化）	LOW-MEDIUM	render-

快速参考

1. 查询键结构（CRITICAL）

tquery-key-factories - 使用集中式查询键工厂
tquery-hierarchical-keys - 键结构从通用到具体
tquery-always-arrays - 始终使用数组查询键
tquery-serializable-objects - 在键中使用可序列化对象
tquery-options-pattern - 使用 queryOptions 实现类型安全的共享
tquery-colocate-keys - 将查询键与功能就近放置

2. 缓存配置（CRITICAL）

cache-staletime-gctime - 理解 staleTime 与 gcTime
cache-global-defaults - 合理配置全局默认值
cache-placeholder-vs-initial - 正确使用 placeholderData 与 initialData
cache-invalidation-precision - 精确失效
cache-refetch-triggers - 控制自动重新获取触发条件
cache-enabled-option - 使用 enabled 或 skipToken 处理条件查询

3. 变更模式（HIGH）

mutation-optimistic-updates - 实现带回滚的乐观更新
mutation-invalidate-onsettled - 根据变更契约选择失效回调
mutation-cancel-queries - 在乐观更新前取消查询
mutation-setquerydata - 使用 setQueryData 立即更新缓存
mutation-avoid-parallel - 避免对同一数据并行变更

4. 预取与请求瀑布（HIGH）

prefetch-avoid-waterfalls - 避免请求瀑布
prefetch-on-hover - 悬停时预取以提升感知速度
prefetch-in-queryfn - 当键已知时启动后续预取
prefetch-server-components - 在 Server Components 中预取
prefetch-infinite-query - 使用 queryClient.infiniteQuery 预取无限列表（5.102+）
prefetch-flatten-api - 扁平化 API 以减少请求瀑布

5. 无限查询（MEDIUM）

infinite-max-pages - 使用 maxPages 限制无限查询页数
infinite-flatten-pages - 扁平化页面以便渲染
infinite-refetch-behavior - 理解无限查询的重新获取行为
infinite-loading-states - 正确处理无限查询的加载状态

6. Suspense 集成（MEDIUM）

suspense-use-suspense-hooks - 使用 Suspense 钩子简化加载状态
suspense-error-boundaries - 始终将 Suspense 与 Error Boundaries 配对
suspense-parallel-queries - 使用 useSuspenseQueries 组合 Suspense 查询
suspense-boundaries-placement - 策略性地放置 Suspense 边界

7. 错误与重试处理（MEDIUM）

error-retry-config - 配置带指数退避的重试
error-conditional-retry - 根据错误类型进行条件重试
error-global-handler - 对常见错误使用全局错误处理器
error-display-patterns - 恰当地展示错误
error-throw-on-error - 配合 Error Boundaries 使用 throwOnError

8. 渲染优化（LOW-MEDIUM）

render-select-memoize - 记忆化 select 函数
render-select-derived - 使用 select 派生数据以减少重新渲染
render-notify-props - 在 notifyOnChangeProps 之前依赖被追踪属性
render-structural-sharing - 理解结构共享
render-tracked-props - 保留被追踪属性优化

使用方式

先在项目根目录运行：

npx -y @pymodel/react-frontend-skills detect                       # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill tanstack-query  # deprecated APIs → rule IDs

针对上述每条与任务匹配的规则，以及每个扫描命中项，阅读 references/<rule-id>.md：了解其重要性，以及错误与正确代码的对比。

技能介绍

用途