important-defaults（重要的默认配置）

开箱即用，TanStack Query 配置了一套激进但合理 的默认值。有时这些默认值会让新用户措手不及，或者如果用户不知道它们，会使学习/调试变得困难。 在你继续学习和使用 TanStack Query 时，请记住以下几点：

通过 useQuery 或 useInfiniteQuery 创建的查询实例，默认情况下会将 缓存数据视为过期（stale） 。

要改变这种行为，你可以使用 staleTime 选项全局地或为每个查询单独进行配置。指定更长的 staleTime 意味着查询不会那么频繁地重新获取数据。

设置了 staleTime 的查询在 staleTime 耗尽之前都被认为是 新鲜（fresh） 的。
- 将 staleTime 设置为例如 2 * 60 * 1000，可以确保数据在 2 分钟内直接从缓存读取，而不会触发任何形式的重新获取，或者直到查询被手动失效（invalidated manually）。
- 将 staleTime 设置为 Infinity，则永远不会触发重新获取，直到查询被手动失效。
- 将 staleTime 设置为 'static'，则永不触发重新获取，即使查询被手动失效也不例外。
过期（Stale） 的查询在以下情况会自动在后台重新获取（Refetch）：
- 新的查询实例挂载时
- 窗口重新获得焦点时
- 网络重新连接时

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

查询可以额外配置 refetchInterval 以定期触发重新获取，这一设置独立于 staleTime。
不再有活跃实例（即没有 useQuery、useInfiniteQuery 或查询观察者在使用它）的查询结果会被标记为"非活动（inactive）"，并保留在缓存中以备稍后再次使用。
默认情况下，"非活动"的查询会在 5 分钟 后被垃圾回收。

要更改此设置，你可以将查询的默认 gcTime 更改为除 1000 * 60 * 5 毫秒以外的其他值。
失败的查询会 静默重试 3 次，并带有指数退避延迟，然后才会捕获并向 UI 显示错误。

要更改此设置，你可以将查询的默认 retry 和 retryDelay 选项更改为除 3 和默认指数退避函数以外的其他值。
查询结果默认进行 结构共享（structurally shared）以检测数据是否实际发生了变化 。如果没有变化，数据引用将保持不变 ，以便更好地配合 useMemo 和 useCallback 实现值稳定。如果这个概念听起来很陌生，别担心！99.9% 的时间你不需要禁用它，它能以零成本让你的应用性能更高。

结构共享仅适用于兼容 JSON 的值，任何其他值类型将始终被视为已更改。例如，如果你因为响应数据过大而遇到性能问题，可以使用 config.structuralSharing 标志禁用此功能。如果你在查询响应中处理非 JSON 兼容的值，且仍想检测数据是否更改，你可以提供自定义函数作为 config.structuralSharing，通过旧值和新值计算结果，并按需保留引用。

延伸阅读

请查看以下文章，以获取关于默认配置的进一步解释：