React-Query中QueryCache状态更新问题的分析与解决方案

问题背景

在使用React-Query构建React Native应用时，开发者经常会遇到需要在全局处理错误的情况。一个典型场景是实现"离线模式"功能，当用户启用离线模式时，需要禁止所有错误提示的显示。然而，在React-Query的QueryCache中，通过onError回调捕获的状态值却无法正确更新，这导致了一个棘手的问题。

问题现象

在实现离线模式功能时，开发者通常会这样做：

1. 创建一个全局的QueryClient实例
2. 在QueryCache的onError回调中检查离线状态
3. 根据离线状态决定是否显示错误提示

然而，当用户切换离线模式开关时，onError回调中获取的状态值始终是初始值，无法反映最新的状态变化。这使得离线模式功能无法正常工作。

问题根源

经过分析，这个问题主要由以下原因造成：

1. 闭包陷阱：onError回调创建时捕获了初始的isOffline值，形成了一个闭包，导致后续状态更新无法反映到回调函数中。

2. QueryClient重建问题：一些开发者尝试通过useMemo在isOffline变化时重建QueryClient实例，这会导致整个缓存被清空，不仅性能低下，而且破坏了应用状态的一致性。

解决方案

针对这个问题，React-Query的核心维护者提出了以下解决方案：

1. 避免依赖闭包状态

不要在onError回调中直接依赖外部状态变量，而是采用命令式的方式获取最新状态。例如：

• 如果使用Zustand状态管理，可以通过store.getState().isOffline直接获取最新状态
• 对于Context API，可以通过ref暴露状态获取方法

2. 保持QueryClient实例稳定

QueryClient实例应该在整个应用生命周期中保持稳定，不应随着状态变化而重建。正确的做法是：

• 在应用初始化时创建一次QueryClient
• 通过命令式API获取最新状态，而不是依赖React的响应式状态

3. 实现示例

// 正确实现方式示例
const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error) => {
      // 命令式获取最新状态
      const isOffline = store.getState().isOffline;
      if (isOffline && error.code === 'NETWORK_ERROR') return;
      showErrorToast(error.message);
    }
  })
});

最佳实践

1. QueryClient单例：确保QueryClient只创建一次，通常放在应用的最外层组件。

2. 状态获取方式：对于需要响应式状态的情况，考虑使用可观察对象或命令式状态获取。

3. 错误处理策略：复杂的错误处理逻辑可以考虑封装成单独的函数，通过依赖注入的方式提供给QueryClient。

4. 性能考虑：避免在错误处理回调中执行昂贵的操作，保持回调函数轻量。

总结

React-Query是一个强大的数据同步库，但在与React状态系统集成时需要注意闭包和实例生命周期的问题。通过采用命令式状态获取和保持QueryClient实例稳定，可以有效地解决QueryCache中状态更新不及时的问题，实现更加可靠的离线模式功能。

对于需要复杂状态交互的场景，建议结合状态管理库如Zustand或Redux，以命令式的方式获取最新状态，这样既能保持性能，又能确保状态一致性。