tanstack-query

TanStack Query

当工作涉及 TanStack Query v5 时使用此技能，尤其是涉及 @tanstack/react-query、服务端状态缓存、查询／变更生命周期问题、SSR 水合，或从 React Query/TanStack Query v4 迁移时。

工作流

1. 修改代码前，先检查本地 Query 的情况：
   • @tanstack/react-query、@tanstack/query-core、devtools、persist/broadcast 软件包、ESLint 插件、React、框架路由器和测试工具的版本。
   • Provider 设置：QueryClient、QueryClientProvider、SSR 请求作用域、默认选项、devtools 和持久化 Provider。
   • 查询约定：查询键工厂、queryOptions、mutationOptions、自定义 Hook、路由加载器、SSR 预取和失效辅助函数。
   • 运行时意图：仅客户端获取、服务端预取和水合、路由预加载、离线／持久化，或多标签页同步。
2. 对于当前行为、软件包差异、SSR、持久化或迁移，刷新相关文档。请从 source-map.md 开始。
3. 对于安装、Provider 设置、默认值、查询键、useQuery 和 TypeScript 选项，请参考 setup-core.md。
4. 对于依赖查询、并行查询、分页查询、无限查询、禁用查询、可取消查询、选择查询和性能敏感型查询，请参考 query-patterns.md。
5. 对于 useMutation、失效处理、直接写入缓存、乐观更新、变更作用域和离线变更，请参考 mutations-cache.md。
6. 对于预取、路由器集成、SSR、水合、Suspense、Server Components 和流式处理注意事项，请参考 ssr-prefetching.md。
7. 对于持久化、广播同步、devtools、ESLint、测试和迁移检查，请参考 production-tooling.md。

实现判断

• 将 TanStack Query 视为服务端状态管理工具，而不是本地客户端 UI 状态的替代品。
• 查询键决定缓存身份。应包含查询函数中用到的所有可变变量，并确保查询键可序列化。
• 在 v5 中，优先使用对象语法。不要重新引入 v3/v4 的位置参数签名。
• 对可复用的查询和变更，优先使用类型化的 queryOptions 和 mutationOptions 辅助函数。
• 对命令式读取和预取，请使用 queryClient.query / queryClient.infiniteQuery（v5.102+）。fetchQuery、prefetchQuery、ensureQueryData 及其无限查询变体已弃用；旧代码中保留现有用法，但不要新增调用。
• 有意识地设置 staleTime。默认情况下，过期数据会在挂载、窗口获得焦点和重新连接时重新获取；这可能是合理的，但如果不了解这一点，也可能造成不必要的请求。
• 变更后默认采用定向失效。如果变更响应已包含准确的更新后对象，则使用不可变的 setQueryData。
• 对于乐观更新，如果只有一个界面需要显示待处理状态，优先使用 UI 层级的 variables；如果多个界面都需要响应，则使用缓存层级的 onMutate 回滚。
• 在 SSR 中，服务端应创建请求作用域的查询客户端，浏览器端应使用稳定的客户端。避免使用模块级服务端缓存，以免在用户之间泄露数据。
• 在测试中，为每个测试隔离使用独立的 QueryClient，关闭重试，并清除或重新创建客户端，而不是共享缓存状态。

验证

优先使用仓库中已有的检查。对于重要的 TanStack Query 变更，请执行相关的部分检查：

• 类型检查：覆盖查询键、查询函数返回值、select、变更变量和 SSR 水合类型。
• 针对失效处理、乐观更新回滚、缓存更新、依赖查询、分页、无限查询和错误状态的重点测试。
• 浏览器冒烟测试：覆盖加载、过期数据、后台获取、分页、变更待处理／错误状态、水合，以及焦点／重新连接行为。
• 修改预取、水合、过期时间或 Provider 位置时，进行 SSR 或路由加载器冒烟测试。
• 如果仓库使用 @tanstack/eslint-plugin-query，则运行 ESLint Query 插件检查。