重要默认设置

开箱即用，TanStack Query 的默认配置是激进但合理的。有时这些默认值可能会让新用户感到意外，或者在用户不知情的情况下增加学习/调试的难度。 在您继续学习和使用 TanStack Query 的过程中，请牢记这些默认值。

• 通过 useQuery 或 useInfiniteQuery 创建的查询实例默认会认为缓存的数据是陈旧的。

要更改此行为，您可以使用 staleTime 选项全局和按查询地配置您的查询。指定更长的 staleTime 意味着查询不会那么频繁地重新获取数据。

• 一个设置了 staleTime 的查询在 staleTime 过期之前，被认为是新鲜的。

  • 将 staleTime 设置为例如 2 * 60 * 1000 毫秒，以确保在 2 分钟内数据从缓存中读取，而不会触发任何重新获取，直到查询被 手动使失效。
  • 将 staleTime 设置为 Infinity，直到查询被 手动使失效 才会触发重新获取。
  • 将 staleTime 设置为 'static'，即使查询被手动使失效，也不会触发重新获取。

• 过时查询会在以下情况下自动在后台重新获取：

  • 查询的新实例挂载
  • 窗口重新获得焦点
  • 网络重新连接

设置 staleTime 是避免过度重新获取的推荐方式，但您也可以通过设置 refetchOnMount、refetchOnWindowFocus 和 refetchOnReconnect 等选项来定制重新获取的时间点。

• 查询还可以选择配置 refetchInterval 以定期触发重新获取，这独立于 staleTime 设置。

• 没有任何活动的 useQuery、useInfiniteQuery 或查询观察器的查询结果被标记为“非活动”并在缓存中保留，以防它们稍后被再次使用。

• 默认情况下，“非活动”查询在 5 分钟后被垃圾回收。

  要更改此行为，您可以将查询的默认 gcTime 改为 1000 * 60 * 5 毫秒以外的其他值。

• 失败的查询会静默重试 3 次，并采用指数退避延迟，然后才会捕获并向 UI 显示错误。

  要更改此行为，您可以将查询的默认 retry 和 retryDelay 选项改为 3 和默认的指数退避函数以外的其他值。

• 查询结果默认在结构上是共享的，以检测数据是否真的发生了变化，如果未改变，数据引用将保持不变，以便更好地与 useMemo 和 useCallback 进行值稳定。如果这个概念对您来说很陌生，那么不用担心！99.9% 的情况下您不需要禁用它，并且它能在不增加任何成本的情况下提高您应用的性能。

  结构共享仅适用于 JSON 兼容的值，任何其他值类型都将被视为已更改。如果您由于例如大型响应而遇到性能问题，您可以使用 config.structuralSharing 标志禁用此功能。如果您在查询响应中处理非 JSON 兼容的值，但仍希望检测数据是否已更改，您可以提供自己的自定义函数作为 config.structuralSharing 来从旧响应和新响应中计算一个值，并在需要时保留引用。

请查看以下社区资源文章，了解更多关于默认值的解释。

• 实用 React Query
• React Query 作为状态管理器
• React Query 思维