React Query 中 QueryCache onError 的异常处理机制解析

理解 QueryCache 的全局错误处理

在 React Query 的使用过程中，QueryCache 提供了一个全局的错误处理机制，通过 onError 回调函数可以捕获所有查询发生的错误。然而，许多开发者在使用时会遇到一个常见误区：试图在 onError 中重新抛出错误，期望外部的 try/catch 能够捕获。

错误处理的基本流程

当使用 fetchQuery 发起一个查询时，React Query 的错误处理遵循以下流程：

1. 查询函数(queryFn)执行并抛出错误
2. QueryCache 的 onError 回调被触发，接收该错误
3. fetchQuery 的 Promise 被拒绝(reject)，携带相同的错误

关键在于，onError 是一个事件处理器(event handler)，它的职责是通知你错误发生了，而不是让你改变错误处理流程。

为什么不应该在 onError 中重新抛出错误

在示例代码中，开发者尝试在 onError 中重新抛出错误，期望外部的 try/catch 能够捕获。这种模式会导致几个问题：

1. 错误处理混乱：查询已经处于错误状态，重新抛出会导致两个错误（原始错误和 onError 抛出的错误）
2. 状态不一致：React Query 无法确定应该缓存哪个错误状态
3. 预期不符：外部 try/catch 无法捕获 onError 中抛出的错误

正确的错误处理模式

正确的做法应该是：

const qc = new QueryClient({
  queryCache: new QueryCache({
    onError: (error) => {
      // 在这里记录错误或发送到监控系统
      console.error('查询错误:', error);
      // 不要重新抛出！
    }
  })
});

async function fetchData() {
  try {
    const data = await qc.fetchQuery({
      queryKey: ['data'],
      queryFn: async () => {
        throw new Error('模拟API错误');
      }
    });
  } catch (e) {
    // 这里会捕获到queryFn抛出的错误
    console.log('捕获到查询错误', e);
  }
}

高级错误处理策略

对于复杂的应用场景，可以考虑以下策略：

1. 分层错误处理：

   • 使用 onError 进行全局错误日志记录
   • 在组件层面处理特定的业务逻辑错误

2. 错误分类：

   onError: (error) => {
     if (error instanceof AuthenticationError) {
       // 处理认证错误
     } else if (error instanceof NetworkError) {
       // 处理网络错误
     }
   }
   

3. 错误边界(Error Boundaries)：

   • 结合 React 的错误边界机制处理渲染时的错误

总结

React Query 的错误处理机制设计得非常明确：onError 用于通知和记录错误，而不应该改变错误处理流程。开发者应该在 onError 中执行副作用操作（如日志记录、错误上报），而在查询调用处处理业务逻辑相关的错误。理解这一设计理念，可以避免许多不必要的错误处理混乱，构建更健壮的应用程序。

记住，良好的错误处理策略应该是分层的、明确的和可预测的。React Query 提供了灵活的工具，但正确的使用方式才能发挥它们的最大价值。