React Query 中 Mutation Filters 的正确使用方式

在 React Query 的文档中，Mutation Filters 是一个非常有用的功能，它允许开发者根据特定条件筛选出当前正在进行的 mutation 操作。然而，文档中关于 predicate 函数的使用示例存在一个容易忽略但重要的错误。

问题背景

Mutation Filters 的 predicate 函数接收一个 mutation 对象作为参数，开发者可以通过这个对象获取 mutation 的各种状态信息。文档中给出的示例代码试图通过 mutation.options.variables 来访问 mutation 的变量数据，但实际上这是不正确的访问方式。

正确的访问方式

经过对 React Query 源码的分析，我们发现 mutation 的变量实际上是存储在 state 属性中，而不是 options 属性中。因此，正确的访问方式应该是：

await queryClient.isMutating({
  predicate: (mutation) => mutation.state.variables?.id === 1,
})

技术细节解析

1. Mutation 对象结构：在 React Query 中，每个 mutation 对象包含多个属性，其中 state 属性存储了 mutation 的当前状态信息，包括 variables、data、error 等。

2. options 属性：虽然 mutation 确实有 options 属性，但它主要包含的是 mutation 的配置信息，如 mutationKey、retry 设置等，而不包含实际的变量数据。

3. 类型安全：在使用 TypeScript 时，错误的访问方式会导致类型错误，因为 TypeScript 类型定义中明确显示 variables 存在于 state 而非 options 中。

实际应用建议

在实际开发中使用 Mutation Filters 时，建议：

1. 始终通过 mutation.state 访问 mutation 的状态数据
2. 对于变量数据，使用 mutation.state.variables
3. 结合 TypeScript 的类型提示可以避免这类错误
4. 在团队开发中，可以将正确的访问方式封装为工具函数或自定义 hook

总结

这个文档错误虽然看起来很小，但却可能导致开发者在实际使用中遇到困惑和错误。理解 React Query 内部数据结构的设计理念对于正确使用其 API 非常重要。Mutation 的状态数据存储在 state 属性中这一设计，与 React Query 的整体架构思想是一致的，即保持配置(options)和状态(state)的清晰分离。

通过这个案例，我们也看到即使是官方文档也可能存在需要修正的地方，作为开发者，在遇到问题时查阅源码往往能快速找到正确答案。