tanstack-query

TanStack Query 最佳实践

面向 TanStack Query v5 应用的全面性能优化指南。涵盖 8 个类别中的 41 条规则，并按影响程度排序，为自动重构和代码生成提供指导。

适用场景

在以下情况下参考这些指南：

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

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	查询键结构	严重	tquery-
2	缓存配置	严重	cache-
3	变更模式	高	mutation-
4	预取与瀑布	高	prefetch-
5	无限查询	中	infinite-
6	Suspense 集成	中	suspense-
7	错误与重试处理	中	error-
8	渲染优化	低至中	render-

快速参考

1. 查询键结构（严重）

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

2. 缓存配置（严重）

• 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. 变更模式（高）

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

4. 预取与瀑布（高）

• 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. 无限查询（中）

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

6. Suspense 集成（中）

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

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

• error-retry-config - 配置指数退避重试
• error-conditional-retry - 根据错误类型使用条件重试
• error-global-handler - 使用全局错误处理器处理常见错误
• error-display-patterns - 以恰当的方式显示错误
• error-throw-on-error - 将 throwOnError 与 Error Boundaries 配合使用

8. 渲染优化（低-中）

• 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

对于上面与任务匹配的每条规则以及每个 scan 命中项，请阅读 references/<rule-id>.md，了解其重要性以及错误与正确的代码示例。

相关技能

• 如需在测试中模拟 API 响应，请参阅 msw 技能
• 如需了解 React 19 数据获取模式，请参阅 react 技能