TanStack Query中useMutation在useEffect中状态卡顿问题解析

问题现象

在使用TanStack Query（原React Query）时，开发者发现当在组件的useEffect钩子中调用useMutation的mutate方法时，会出现一个奇怪的现象：虽然onSuccess和onSettled回调能够正常触发，但mutation.status和mutation.data状态却不会更新，始终保持在'pending'状态。

问题根源

这个问题主要与React的严格模式(Strict Mode)和TanStack Query的内部实现机制有关：

1. 严格模式的双重渲染：在严格模式下，React会故意双重渲染组件，以帮助开发者发现潜在问题。这导致useEffect中的逻辑会被执行两次。

2. 状态跟踪机制：TanStack Query内部使用useState来初始化observer（观察者），在严格模式下这个observer也会被初始化两次。当只在"第一个observer"上执行mutate时，由于observer被销毁，状态变更将不再被跟踪。

3. 回调与状态的差异：回调函数（如onSuccess）是在缓存级别触发的，即使mutation卸载也会执行；而状态更新则依赖于组件内部的observer机制。

解决方案

对于这个问题的解决，有以下几种推荐方案：

1. 避免在useEffect中使用mutate：从设计理念上讲，mutations应该与用户操作直接关联，而不是依赖于渲染效果。考虑在按钮点击等用户交互事件中触发mutate。

2. 使用useMutationState：如果需要获取mutation状态，可以使用useMutationState钩子，它能正确跟踪状态变化。

3. 等待React 19的useEffectEvent：未来的React版本将引入useEffectEvent，它能在严格模式下只运行一次，可能解决此类问题。

4. 移除严格模式下的workaround：如果移除了防止双重执行的ref workaround，虽然会看到mutation执行两次，但状态跟踪会恢复正常。

最佳实践建议

1. 区分mutation触发场景：对于需要在模态框打开时触发的操作，考虑：

   • 在打开模态框的按钮点击时触发
   • 使用事件驱动的架构
   • 将mutation提升到父组件

2. 理解严格模式的意义：严格模式下的行为差异实际上是React在帮助我们发现潜在问题，应该借此机会重新思考组件设计。

3. 状态管理选择：对于需要跨组件共享的状态，考虑使用TanStack Query提供的useMutationState或其他状态管理方案。

总结

这个问题揭示了React渲染机制与状态管理库交互时可能出现的边界情况。作为开发者，理解这些底层机制有助于我们编写更健壮的代码。在TanStack Query的使用中，遵循"mutation与用户操作直接关联"的设计原则，可以避免大多数此类问题。对于确实需要在渲染效果中触发操作的特殊场景，可以考虑上述解决方案或等待React新特性的支持。