tanstack-query-best-practices

TanStack Query 最佳实践

在 React 应用中实现 TanStack Query（React Query）模式的综合指南。这些规则可优化数据获取、缓存、变更和服务器状态同步。

适用场景

• 创建新的数据获取逻辑
• 设置查询配置
• 实现变更和乐观更新
• 配置缓存策略
• 集成 SSR/SSG
• 重构现有数据获取代码

按优先级划分的规则类别

优先级	类别	规则	影响
CRITICAL	查询键	5 条规则	防止缓存错误和数据不一致
CRITICAL	缓存	5 条规则	优化性能和数据新鲜度
HIGH	变更	6 条规则	确保数据完整性和 UI 一致性
HIGH	错误处理	3 条规则	避免糟糕的用户体验
MEDIUM	预取	4 条规则	提升感知性能
MEDIUM	并行查询	2 条规则	支持动态并行获取
MEDIUM	无限查询	3 条规则	防止分页错误
MEDIUM	SSR 集成	4 条规则	实现正确的水合
LOW	性能	4 条规则	减少不必要的重新渲染
LOW	离线支持	2 条规则	支持离线优先模式

快速参考

查询键（前缀：qk-）

• qk-array-structure — 查询键始终使用数组
• qk-include-dependencies — 包含查询依赖的所有变量
• qk-hierarchical-organization — 按层级组织键（实体 → ID → 筛选条件）
• qk-factory-pattern — 在复杂应用中使用查询键工厂
• qk-serializable — 确保所有键部分均可序列化为 JSON

缓存（前缀：cache-）

• cache-stale-time — 根据数据变化程度设置适当的 staleTime
• cache-gc-time — 配置 gcTime 以保留不活跃的查询
• cache-defaults — 在 QueryClient 层级设置合理的默认值
• cache-invalidation — 优先使用针对性失效，而非宽泛模式
• cache-placeholder-vs-initial — 了解占位数据与初始数据的区别

变更（前缀：mut-）

• mut-invalidate-queries — 变更后始终使相关查询失效
• mut-optimistic-updates — 实现乐观更新，让 UI 响应更灵敏
• mut-rollback-context — 通过 onMutate 提供回滚上下文
• mut-error-handling — 妥善处理变更错误
• mut-loading-states — 使用 isPending 表示变更加载状态
• mut-mutation-state — 使用 useMutationState 跨组件跟踪状态

错误处理（前缀：err-）

• err-error-boundaries — 配合 useQueryErrorResetBoundary 使用错误边界
• err-retry-config — 适当配置重试逻辑
• err-fallback-data — 在适当情况下提供回退数据

预取（前缀：pf-）

• pf-intent-prefetch — 根据用户意图（悬停、聚焦）预取
• pf-route-prefetch — 在路由切换期间预取数据
• pf-stale-time-config — 预取时设置 staleTime
• pf-ensure-query-data — 使用 ensureQueryData 进行条件预取

无限查询（前缀：inf-）

• inf-page-params — 始终提供 getNextPageParam
• inf-loading-guards — 获取更多数据前检查 isFetchingNextPage
• inf-max-pages — 对于大型数据集，可考虑设置 maxPages

SSR 集成（前缀：ssr-）

• ssr-dehydration — 使用 dehydrate/hydrate 模式实现 SSR
• ssr-client-per-request — 为每个请求创建 QueryClient
• ssr-stale-time-server — 在服务端设置较高的 staleTime
• ssr-hydration-boundary — 使用 HydrationBoundary 包裹

并行查询（前缀：parallel-）

• parallel-use-queries — 使用 useQueries 实现动态并行查询
• query-cancellation — 正确实现查询取消

性能（前缀：perf-）

• perf-select-transform — 使用 select 转换/筛选数据
• perf-structural-sharing — 利用结构共享
• perf-notify-change-props — 使用 notifyOnChangeProps 限制重新渲染
• perf-placeholder-data — 使用 placeholderData 实现即时 UI

离线支持（前缀：offline-）

• network-mode — 配置网络模式以支持离线
• persist-queries — 配置查询持久化以支持离线

使用方法

rules/ 目录中的每个规则文件都包含：

1. 说明 — 为什么这种模式很重要
2. 错误示例 — 应避免的反模式
3. 正确示例 — 推荐的实现方式
4. 上下文 — 何时应用或跳过此规则

完整参考

如需详细指导和代码示例，请参阅 rules/ 目录中的各个规则文件。