React Query 中 setQueryData 方法的使用注意事项

概述

在使用 React Query 进行状态管理时，setQueryData 是一个非常有用的方法，它允许开发者直接更新缓存中的查询数据。然而，在实际使用过程中，如果不注意一些细节，可能会导致意想不到的问题。

常见问题场景

一个典型的错误场景是尝试更新一个不存在的查询数据。例如：

this._queryClient.setQueryData(['foo'], (values: foo[]) => {
    const index = values.findIndex((value) => value.id === id)
    values.splice(index, 1)
    return values
})

当查询键 ['foo'] 对应的数据不存在时，values 参数会是 undefined，此时调用 values.findIndex 就会抛出错误。

问题分析

1. 错误处理机制：React Query 内部会捕获这类错误，并通过 onError 回调进行处理。如果没有显式设置错误处理，开发者可能不会在控制台看到错误信息。

2. 类型安全问题：使用 TypeScript 时，如果没有正确的类型提示，这类问题可能难以发现。

解决方案

1. 添加数据存在性检查：

this._queryClient.setQueryData(['foo'], (values: foo[] | undefined) => {
    if (!values) return []
    const index = values.findIndex((value) => value.id === id)
    values.splice(index, 1)
    return values
})

2. 使用 queryOptions 和 mutationOptions：

React Query 提供了 queryOptions 和 mutationOptions 来增强类型安全性和开发体验。这些选项可以帮助开发者在编码阶段就发现潜在问题。

3. 错误处理：

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      onError: (error) => console.error('Query Error:', error)
    },
    mutations: {
      onError: (error) => console.error('Mutation Error:', error)
    }
  }
})

最佳实践

1. 始终考虑数据可能不存在的情况
2. 充分利用 TypeScript 的类型系统
3. 设置适当的错误处理机制
4. 使用 queryOptions 和 mutationOptions 来组织查询和变更逻辑

总结

React Query 是一个强大的状态管理工具，但像任何工具一样，需要正确使用才能发挥最大价值。理解 setQueryData 方法的行为和潜在陷阱，可以帮助开发者编写更健壮的代码。通过类型安全、错误处理和防御性编程的结合，可以避免许多常见问题。

对于 Angular 开发者来说，虽然示例中使用的是 React Query 的 Angular 适配器，但这些原则同样适用。正确使用这些模式将带来更好的开发体验和更可靠的应用程序。