TanStack Query 中查询状态管理的陷阱与解决方案

问题背景

在使用 TanStack Query（特别是 solid-query 适配器）时，开发者可能会遇到一个隐蔽但影响重大的问题：当组件卸载后，查询仍然保持活跃状态并继续执行数据获取操作。这种情况违背了 TanStack Query 的核心设计原则——查询的生命周期应该与组件的生命周期保持一致。

问题现象

在正常情况下，当组件卸载时，与之关联的查询应该自动变为非活跃状态，停止数据获取。但在某些特定场景下，特别是在以下两种情况下会出现异常：

1. 微任务队列干扰：当查询结果更新与组件卸载操作发生在同一个事件循环中，且使用了微任务（如 queueMicrotask）进行调度时
2. 时序敏感操作：当导航操作（如路由跳转）与查询失效操作同时发生时

技术原理分析

问题的根源在于 TanStack Query 内部的状态管理机制。在旧版本中，查询订阅者管理存在一个关键缺陷：

1. 查询失效触发重新获取数据
2. 订阅回调执行，其中包含一个微任务调度
3. 组件卸载，清理订阅者
4. 微任务执行，重新添加订阅者

这种时序问题导致查询在应该变为非活跃状态后，又被重新激活，而且新添加的订阅者永远不会被清理，形成"僵尸订阅"。

解决方案

该问题已在 TanStack Query v5.56.1 及更高版本中得到修复。新版本改进了订阅者管理机制，确保：

1. 组件卸载时能正确清理所有订阅
2. 微任务调度不会意外重新激活已清理的查询
3. 查询状态转换更加可靠

最佳实践

为了避免类似问题，开发者应该：

1. 保持 TanStack Query 及其适配器版本为最新
2. 避免在查询回调中直接使用微任务调度
3. 对于复杂的状态转换，考虑使用 React/Solid 的生命周期钩子进行显式管理
4. 在路由导航等关键操作前后，显式处理查询状态

总结

状态管理库的订阅机制是前端开发中的复杂问题，特别是在异步操作和微任务调度交织的场景下。TanStack Query 的这次修复提醒我们，即使是成熟的库也可能存在边界条件下的问题。保持库版本更新，理解底层原理，才能在遇到问题时快速定位和解决。