mcpField
R
react-query-best-practices

react-query-best-practices

github.com/arraydude开发2339 次安装15 周前更新
代码仓库

关于 react-query-best-practices

面向 React Query v4 开发者的实践指南，整理了查询、变更、缓存、WebSocket、TypeScript、测试和迁移等规则。内容按影响优先级组织，并附有错误与正确示例的规则文件入口。

主要功能

  1. 01覆盖查询键与查询模式
  2. 02指导变更、缓存更新和乐观更新
  3. 03说明缓存策略与 WebSocket 集成
  4. 04提供 TypeScript 和测试建议
  5. 05整理 React Query v5 迁移要点

适用场景

  1. 01设计一致的查询键和依赖项
  2. 02处理变更后的缓存失效与更新
  3. 03排查 WebSocket 和查询缓存问题
  4. 04规划从 v4 迁移到 v5

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/arraydude/agent-skills --skill react-query-best-practices

安装后在 Claude Code 中输入/react-query-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

AGENTS.md
rules/
cache-refetch-triggers.md
cache-stale-time.md
migration-cache-time-to-gc-time.md
migration-context-to-query-client.md
migration-hydration-boundary.md
migration-initial-page-param.md
migration-keep-previous-data.md
migration-misc-breaking-changes.md
migration-query-callbacks-removed.md
migration-refetch-interval-callback.md
migration-refetch-page-to-max-pages.md
migration-remove-method.md
migration-single-signature.md
migration-status-pending.md
migration-suspense-hooks.md
migration-throw-on-error.md
mutation-callback-separation.md
mutation-direct-cache-update.md
mutation-invalidation.md
mutation-optimistic-updates.md
mutation-prefer-mutate.md
query-dependent-enabled.md
query-key-factory.md
query-keys-as-dependencies.md
query-placeholder-vs-initial.md
query-select-transforms.md
query-status-check-order.md
query-tracked-properties.md
testing-fresh-client.md

详细介绍

React Query 最佳实践

重要： 本指南面向 React Query v4。部分模式在 v5 中可能有所不同。

基于 TkDodo 权威博客系列编写的 React Query v4（TanStack Query）综合指南。包含 7 个类别中的 24 条规则，并按影响程度排序。

适用场景

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

  • 实现新的查询或 mutation
  • 将 WebSockets 集成到 React Query
  • 设置查询失效模式
  • 调试 React Query 的行为
  • 优化渲染性能
  • 处理 TypeScript 集成问题

按优先级划分的规则类别

优先级类别影响前缀
1查询键与模式CRITICALquery-
2Mutation 与更新CRITICALmutation-
3缓存策略HIGHcache-
4WebSocket 集成HIGHwebsocket-
5TypeScript 集成MEDIUMtypescript-
6测试模式MEDIUMtesting-
7常见陷阱MEDIUMtroubleshoot-
8迁移到 v5HIGHmigration-

快速参考

1. 查询键与模式（CRITICAL）
  • query-keys-as-dependencies - 将所有 queryFn 参数包含在 queryKey 中
  • query-key-factory - 使用工厂模式，统一生成键
  • query-select-transforms - 使用 select 选项转换数据
  • query-status-check-order - 先检查数据，再检查错误，最后检查加载状态
  • query-tracked-properties - 只解构实际使用的属性
  • query-placeholder-vs-initial - 了解何时使用每种方式
  • query-dependent-enabled - 使用 enabled 选项处理依赖查询
2. Mutation 与更新（CRITICAL）
  • mutation-prefer-mutate - 优先使用带回调的 mutate()，而非 mutateAsync()
  • mutation-invalidation - Mutation 后使查询失效
  • mutation-direct-cache-update - 适当时直接更新缓存
  • mutation-optimistic-updates - 立即显示成功，失败时回滚
  • mutation-callback-separation - 在 Hook 中处理查询逻辑，在组件中处理 UI 效果
3. 缓存策略（HIGH）
  • cache-stale-time - 根据业务场景设置合适的 staleTime
  • cache-refetch-triggers - 在生产环境中保持启用 refetch 触发器
4. WebSocket 集成（HIGH）
  • websocket-event-invalidation - 使用事件触发失效
  • websocket-stale-time-infinity - 为由 WS 管理的数据设置 staleTime: Infinity
  • websocket-reconnection - 重连时使过期查询失效
5. TypeScript 集成（MEDIUM）
  • typescript-infer-dont-specify - 让 TypeScript 自动推断，并为 queryFn 指定类型
  • typescript-zod-validation - 使用 Zod 进行运行时验证
6. 测试模式（MEDIUM）
  • testing-fresh-client - 为每个测试创建新的 QueryClient
  • testing-msw-mocking - 使用 MSW 模拟网络请求
7. 常见陷阱（MEDIUM）
  • troubleshoot-copy-to-state - 绝不要将查询数据复制到本地状态
  • troubleshoot-missing-key-deps - 将所有依赖项包含在查询键中
  • troubleshoot-fetch-not-reject - 使用 fetch 时处理 HTTP 错误
8. 迁移到 v5（高优先级）
  • migration-single-signature - 所有钩子现在都接受单个对象参数
  • migration-status-pending - 状态从 'loading' 变为 'pending'；isLoading 的语义发生变化
  • migration-cache-time-to-gc-time - cacheTime 重命名为 gcTime
  • migration-keep-previous-data - keepPreviousData 替换为带有 identity fn 的 placeholderData
  • migration-query-callbacks-removed - 从 useQuery 中移除 onSuccess/onError/onSettled
  • migration-suspense-hooks - 新增 useSuspenseQuery、useSuspenseInfiniteQuery 钩子
  • migration-throw-on-error - useErrorBoundary 重命名为 throwOnError
  • migration-remove-method - 移除 query.remove()；改用 queryClient.removeQueries()
  • migration-initial-page-param - 无限查询现在必须设置 initialPageParam
  • migration-refetch-page-to-max-pages - refetchPage 替换为 maxPages
  • migration-hydration-boundary - Hydrate 组件重命名为 HydrationBoundary
  • migration-refetch-interval-callback - refetchInterval 回调现在只接收 query
  • migration-context-to-query-client - 移除 context 属性；直接传入 queryClient
  • migration-misc-breaking-changes - 最低要求 React 18、服务端 retry=0、hashKey、isDataEqual 等

核心心智模型

  1. React Query 不是数据获取库 - 它是一个异步状态管理器
  2. 服务端状态 != 客户端状态 - 切勿在全局状态管理器中混用两者
  3. 过期后重新验证 - 立即显示缓存数据，并在后台获取数据
  4. 查询键是依赖项 - 在 queryFn 中包含使用的所有变量

如何使用

阅读各规则文件，了解详细说明和代码示例：

rules/query-key-factory.md
rules/mutation-invalidation.md
rules/websocket-event-invalidation.md

每个规则文件都包含：

  • 简要说明其重要性
  • 错误代码示例
  • 正确代码示例

完整编译文档

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

评论

支持 Markdown