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

在 TanStack Query 的日常开发中，Mutation Filters 是一个非常有用的功能，它允许开发者对正在进行的 mutation 操作进行筛选和查询。然而，文档中的一个示例可能会误导开发者，本文将详细解析这个问题并提供正确的解决方案。

问题背景

Mutation Filters 的 predicate 函数用于自定义筛选条件，开发者可以通过它来检查特定的 mutation 是否符合某些条件。在官方文档中，给出了一个通过变量 ID 筛选 mutation 的示例：

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

这个示例看似合理，但实际上存在一个关键问题：variables 并不存在于 mutation.options 上。

深入源码分析

通过查看 TanStack Query 的源码，我们可以发现 mutation 的结构定义：

1. Mutation 类型中的 options 属性确实不包含 variables 字段
2. 实际的 mutation 状态（包括变量）存储在 state 属性中

正确的变量访问路径应该是 mutation.state.variables，而不是文档中所示的 mutation.options.variables。

正确用法

修正后的代码示例如下：

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

为什么这很重要

理解 mutation 状态的实际存储位置对于：

1. 编写正确的筛选逻辑至关重要
2. 避免运行时错误
3. 提高代码的可维护性

最佳实践建议

在使用 Mutation Filters 时，建议开发者：

1. 始终查阅最新的类型定义
2. 了解 mutation 的生命周期和状态管理
3. 在复杂筛选条件下编写单元测试

总结

TanStack Query 是一个功能强大但细节丰富的库，正确理解其内部数据结构对于有效使用各种高级功能至关重要。通过本文的分析，希望开发者能够避免这个常见的陷阱，更加自信地使用 Mutation Filters 功能。