tanstack-query

TanStack Query 最佳实践

面向 TanStack Query v5 应用的全面性能优化指南。包含 8 个类别中的 40 条规则，并根据影响优先级排序，以指导自动重构和代码生成。

适用场景

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

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

按优先级划分的规则类别

优先级	类别	影响	前缀
1	查询键结构	CRITICAL	tquery-
2	缓存配置	CRITICAL	cache-
3	变更模式	HIGH	mutation-
4	预取与瀑布流	HIGH	prefetch-
5	无限查询	MEDIUM	infinite-
6	Suspense 集成	MEDIUM	suspense-
7	错误与重试处理	MEDIUM	error-
8	渲染优化	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 实现条件查询

3. 变更模式（HIGH）

• mutation-optimistic-updates - 实施可回滚的乐观更新
• mutation-invalidate-onsettled - 在 onSettled 中使缓存失效，而不是在 onSuccess 中
• mutation-cancel-queries - 在乐观更新前取消查询
• mutation-setquerydata - 使用 setQueryData 立即更新缓存
• mutation-avoid-parallel - 避免对相同数据执行并行变更

4. 预取与瀑布流（HIGH）

• prefetch-avoid-waterfalls - 避免请求瀑布流
• prefetch-on-hover - 在悬停时预取，提升感知速度
• prefetch-in-queryfn - 在 queryFn 中预取依赖数据
• prefetch-server-components - 在 Server Components 中预取
• 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 - 将 throwOnError 与 Error Boundaries 配合使用

8. 渲染优化（低-中）

• render-select-memoize - 对 select 函数进行记忆化
• render-select-derived - 使用 select 派生数据，减少重新渲染
• render-notify-props - 使用 notifyOnChangeProps 限制重新渲染
• render-structural-sharing - 了解结构共享
• render-tracked-props - 避免解构所有属性

如何使用

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 分类结构和影响级别
• 参考文件：references/{prefix}-{slug}.md

每个参考文件都包含：

• 简要说明其重要性
• 错误的代码示例及说明
• 正确的代码示例及说明
• 补充背景信息和参考资料

相关技能

• 如需生成类型安全的查询钩子，请参阅 orval 技能
• 如需在测试中模拟 API 响应，请参阅 test-msw 技能
• 如需了解 React 19 数据获取模式，请参阅 react-19 技能

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md