Deepdive into Tanstack/React Query - 4. 重试与网络管理
TanStack Query 提供了强大的重试机制和网络状态管理能力，确保在不稳定的网络环境下也能优雅地处理数据请求。本章将深入分析 retryer.ts、focusManager.ts 和 onlineManager.ts 的源码实现。
4.1 Retryer 重试机制
Retryer 是 TanStack Query 中负责处理请求重试逻辑的核心模块。它封装了失败重试、延迟策略、暂停/继续等复杂逻辑。
4.1.1 createRetryer 函数解析
createRetryer 是一个工厂函数，用于创建管理异步操作重试逻辑的 Retryer 对象：
核心配置接口：
Retryer 返回的接口：
4.1.2 重试策略：retry 与 retryDelay
retry 参数
retry 决定了何时以及是否进行重试：
重试判断逻辑：
retryDelay 参数
retryDelay 控制重试之间的等待时间：
指数退避示例：
| 失败次数 | 延迟时间 |
| 1 | 2000ms (2秒) |
| 2 | 4000ms (4秒) |
| 3 | 8000ms (8秒) |
| 4 | 16000ms (16秒) |
| 5+ | 30000ms (30秒，最大值) |
4.1.3 状态回调：onFail、onPause、onContinue
Retryer 提供了多个生命周期回调，让调用方能够感知和响应状态变化：
回调使用场景：
4.1.4 核心执行流程：run 函数
run 函数是 Retryer 的核心，它实现了完整的重试循环：
流程图：
4.1.5 与 AbortController 的配合
Retryer 通过 CancelledError 与取消逻辑配合：
在 Query 中的集成：
4.2 NetworkMode 网络模式
NetworkMode 控制 TanStack Query 如何响应网络状态变化，决定请求是否应该执行或暂停。
4.2.1 三种网络模式
type NetworkMode = 'online' | 'always' | 'offlineFirst'1. online（默认模式）
- 只有在网络在线时才执行请求
- 离线时请求会暂停，直到网络恢复
- 最适合大多数应用场景
2. always
- 无论网络状态如何，始终执行请求
- 适用于不依赖网络的数据源（如 IndexedDB、Service Worker）
- 也适用于测试环境
3. offlineFirst
- 首次请求会立即执行，无论网络状态
- 重试时才会考虑网络状态
- 适用于有本地缓存或 Service Worker 的场景
模式对比表：
| 特性 | online | always | offlineFirst |
| 首次请求需要网络 | ✅ | ❌ | ❌ |
| 重试需要网络 | ✅ | ❌ | ✅ |
| 网络恢复后自动继续 | ✅ | N/A | ✅ |
| 适用场景 | 标准 API | 本地数据 | PWA/缓存优先 |
4.2.2 canRun 与请求暂停逻辑
canStart 和 canContinue 是控制请求执行的两个关键函数：
关键区别：
canStart：只检查网络状态（通过canFetch）canContinue：同时检查焦点状态和网络状态
这意味着：
- 请求启动时只需要网络可用
- 重试继续时还需要窗口处于焦点状态
4.2.3 onlineManager 状态管理
onlineManager 是一个单例，负责追踪和广播网络连接状态：
自定义事件监听器：
4.3 FocusManager 与 OnlineManager
这两个管理器都继承自 Subscribable 基类，实现了发布-订阅模式。
4.3.1 Subscribable 发布订阅基础
Subscribable 是一个通用的发布-订阅基类：
继承关系图：
4.3.2 FocusManager 实现
FocusManager 管理窗口/标签页的焦点状态：
默认事件绑定（浏览器环境）：
4.3.3 OnlineManager 实现
OnlineManager 的实现与 FocusManager 类似：
默认事件绑定：
4.3.4 自定义事件处理器
两个 Manager 都支持自定义事件处理，适用于特殊场景：
React Native 示例
自定义 Focus 检测（如 React Native）
4.3.5 与 QueryCache 的集成
这两个 Manager 与 QueryCache 紧密集成，当状态变化时触发重新获取：
4.4 完整流程示例
让我们通过一个完整的示例来理解这些机制如何协同工作：
执行流程：
4.5 最佳实践
1. 根据场景选择 NetworkMode
2. 智能重试策略
3. 测试环境配置
小结
本章深入分析了 TanStack Query 的重试与网络管理机制：
- Retryer 是一个精心设计的重试状态机，支持灵活的重试策略、指数退避延迟，以及暂停/继续语义
- NetworkMode 提供了三种模式来适应不同的网络场景，从严格的在线要求到完全离线优先
- FocusManager 和 OnlineManager 基于发布-订阅模式，监听浏览器事件并协调数据的自动刷新
这些机制共同构成了 TanStack Query 强大的网络弹性能力，让应用在各种网络条件下都能提供良好的用户体验。