TanStack Query v5 性能优化指南：40条最佳实践提升应用性能

tanstack-query by pproenca/dot-skills

153 周安装量

86 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/pproenca/dot-skills --skill tanstack-query

JavaScript 框架性能优化前端架构

🇨🇳中文介绍

TanStack Query 最佳实践

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

何时应用

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

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

按优先级划分的规则类别

优先级	类别	影响	前缀
1	查询键结构	关键	`tquery-`
2	缓存配置	关键	`cache-`
3	变更模式	高

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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 选项处理条件查询

3. 变更模式（高）

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

4. 预取与瀑布流（高）

prefetch-avoid-waterfalls - 避免请求瀑布流
prefetch-on-hover - 在悬停时预取以提高感知速度
prefetch-in-queryfn - 在 queryFn 中预取依赖数据
prefetch-server-components - 在服务器组件中预取
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 钩子简化加载状态
suspense-error-boundaries - 始终将 Suspense 与错误边界配对使用
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

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

🇺🇸English

TanStack Query Best Practices

Comprehensive performance optimization guide for TanStack Query v5 applications. Contains 40 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

Writing new queries, mutations, or data fetching logic
Implementing caching strategies (staleTime, gcTime)
Reviewing code for performance issues or request waterfalls
Refactoring existing TanStack Query code
Implementing infinite queries, Suspense, or optimistic updates

Rule Categories by Priority

Priority	Category	Impact	Prefix
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	MEDIUM	`suspense-`
7	Error & Retry Handling	MEDIUM	`error-`
8	Render Optimization	LOW-MEDIUM	`render-`

Quick Reference

1. Query Key Structure (CRITICAL)

tquery-key-factories - Use centralized query key factories
tquery-hierarchical-keys - Structure keys from generic to specific
tquery-always-arrays - Always use array query keys
tquery-serializable-objects - Use serializable objects in keys
tquery-options-pattern - Use queryOptions for type-safe sharing
tquery-colocate-keys - Colocate query keys with features

2. Caching Configuration (CRITICAL)

cache-staletime-gctime - Understand staleTime vs gcTime
cache-global-defaults - Configure global defaults appropriately
cache-placeholder-vs-initial - Use placeholderData vs initialData correctly
cache-invalidation-precision - Invalidate with precision
cache-refetch-triggers - Control automatic refetch triggers
cache-enabled-option - Use enabled for conditional queries

3. Mutation Patterns (HIGH)

mutation-optimistic-updates - Implement optimistic updates with rollback
mutation-invalidate-onsettled - Invalidate in onSettled, not onSuccess
mutation-cancel-queries - Cancel queries before optimistic updates
mutation-setquerydata - Use setQueryData for immediate cache updates
mutation-avoid-parallel - Avoid parallel mutations on same data

4. Prefetching & Waterfalls (HIGH)

prefetch-avoid-waterfalls - Avoid request waterfalls
prefetch-on-hover - Prefetch on hover for perceived speed
prefetch-in-queryfn - Prefetch dependent data in queryFn
prefetch-server-components - Prefetch in Server Components
prefetch-flatten-api - Flatten API to reduce waterfalls

5. Infinite Queries (MEDIUM)

infinite-max-pages - Limit infinite query pages with maxPages
infinite-flatten-pages - Flatten pages for rendering
infinite-refetch-behavior - Understand infinite query refetch behavior
infinite-loading-states - Handle infinite query loading states correctly

6. Suspense Integration (MEDIUM)

suspense-use-suspense-hooks - Use Suspense hooks for simpler loading states
suspense-error-boundaries - Always pair Suspense with Error Boundaries
suspense-parallel-queries - Combine Suspense queries with useSuspenseQueries
suspense-boundaries-placement - Place Suspense boundaries strategically

7. Error & Retry Handling (MEDIUM)

error-retry-config - Configure retry with exponential backoff
error-conditional-retry - Use conditional retry based on error type
error-global-handler - Use global error handler for common errors
error-display-patterns - Display errors appropriately
error-throw-on-error - Use throwOnError with Error Boundaries

8. Render Optimization (LOW-MEDIUM)

render-select-memoize - Memoize select functions
render-select-derived - Use select to derive data and reduce re-renders
render-notify-props - Use notifyOnChangeProps to limit re-renders
render-structural-sharing - Understand structural sharing
render-tracked-props - Avoid destructuring all properties

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Reference files: references/{prefix}-{slug}.md

Each reference file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

Related Skills

For generating type-safe query hooks, see orval skill
For mocking API responses in tests, see test-msw skill
For React 19 data fetching patterns, see react-19 skill

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Weekly Installs

153

Repository

pproenca/dot-skills

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode130

gemini-cli126

codex125

github-copilot119

cursor115

claude-code111

Flutter应用架构设计指南：分层结构、数据层实现与最佳实践

4,300 周安装