TanStack查询优化Skill tanstack-query

---

name: tanstack-query description: TanStack Query v5数据获取、缓存、变异和查询模式的性能优化。该技能应在使用useQuery、useMutation、queryClient、预取模式或TanStack Query缓存时使用。该技能不涵盖从OpenAPI生成查询钩子（使用orval技能）或在测试中模拟API响应（使用test-msw技能）。 license: MIT metadata: author: community version: “1.0.0”

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 - 在服务器组件中预取
• 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与错误边界配对
• 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与错误边界

8. 渲染优化 (LOW-MEDIUM)

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

如何使用

阅读个别参考文件以获取详细解释和代码示例：

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

每个参考文件包含：

• 简要解释其重要性
• 错误代码示例及解释
• 正确代码示例及解释
• 额外上下文和参考

相关技能

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

完整编译文档

完整指南，所有规则扩展：AGENTS.md