Deepdive into Tanstack/React Query - 5. 自动重新获取

本文深入分析 Tanstack Query 的自动重新获取（Auto Refetch）机制。这是 Query 实现「数据始终新鲜」目标的核心功能之一。

5.1 refetchInterval 定期刷新

refetchInterval 允许 Query 按固定时间间隔自动重新获取数据，适用于需要轮询的场景（如实时数据面板、消息通知等）。

配置选项

refetchInterval 支持以下值：

• number：毫秒数，表示刷新间隔
• false：禁用定期刷新
• (query) => number | false：函数形式，可根据 query 状态动态返回间隔

#updateRefetchInterval 实现

在 QueryObserver 中，#updateRefetchInterval 方法负责管理定时器：

核心逻辑：

1. 清除旧定时器：避免多个定时器同时运行
2. 检查禁用条件：false 或网络模式不允许时跳过
3. 创建 setInterval：按间隔执行 #executeFetch
4. 后台检查：根据 refetchIntervalInBackground 和 focusManager.isFocused() 决定是否在后台执行

#computeRefetchInterval 计算逻辑

当 refetchInterval 是函数时，需要动态计算：

这个方法在以下时机被调用：

• Observer 订阅时
• 每次 notify 触发后
• Query 状态变化时

清理机制

在 Observer 销毁（destroy）或更新 interval 时调用。

5.2 refetchOnWindowFocus 窗口聚焦刷新

当用户从其他标签页/应用切回时，自动刷新数据。这是 Tanstack Query 默认开启的特性。

配置选项

可选值：

• true（默认）：窗口聚焦时，如果数据过期则刷新
• false：禁用此功能
• 'always'：窗口聚焦时始终刷新，无视 staleTime

触发条件与 shouldFetchOnWindowFocus

在 QueryObserver 中的判断逻辑：

从 FocusManager 到 QueryCache.onFocus 的流程

完整的事件流程如下：

FocusManager 源码

QueryCache.onFocus

使用 notifyManager.batch 批量处理，避免多次渲染。

Query.onFocus

只要有一个 Observer 需要刷新，就执行 refetch。

5.3 refetchOnReconnect 网络恢复刷新

当网络从离线恢复到在线状态时，自动刷新数据。

配置选项

配置值与 refetchOnWindowFocus 相同：

• true（默认）：网络恢复时，数据过期则刷新
• false：禁用
• 'always'：网络恢复时始终刷新

触发条件与 shouldFetchOnReconnect

与 networkMode 的配合

refetchOnReconnect 与 networkMode 协同工作：

NetworkMode 影响

OnlineManager 源码

QueryCache.onOnline

Query.onOnline

与 onFocus 类似，但额外处理了因 networkMode: 'online' 而暂停的请求。

canFetch 函数

判断当前网络状态是否允许发起请求：

• networkMode: 'online'：需要在线才能 fetch
• networkMode: 'always'：始终可以 fetch
• networkMode: 'offlineFirst'：始终可以 fetch

小结

三种自动重新获取机制的对比：

最佳实践

1. 合理设置 staleTime：配合 refetchOnWindowFocus 避免频繁刷新

1. 轮询场景优化：使用动态 interval

1. 离线优先应用：配置 networkMode

下一篇将深入分析 Mutation 变更操作，包括乐观更新、变更队列管理等核心机制。