tanstack-query

本技能为 TanStack Query v5 提供全面的实作指南，专注于现代 React 应用程序中高效的异步状态管理。它专为需要处理复杂服务器状态、数据获取和缓存失效的工程师设计。本技能涵盖了从 v4 到 v5 的迁移过程，包括单对象 Hook 签名、gcTime 配置以及移除旧版回调属性。它作为查询键工厂、乐观更新和 SSR 集成等架构模式的中心化参考，确保 SPA 与 Next.js 或 Remix 等框架的一致性性能。

• 实现标准化的查询键工厂，以防止缓存键冲突并确保类型安全。

• 配置生产等级的预设值，包括 staleTime、gcTime 和重试逻辑，以减少服务器负载并提升用户体验。

• 提供进阶变更工作流的模式，包括乐观 UI 更新以及通过 QueryCache 全局回调实现的稳健错误处理。

• 支持服务器端渲染 (SSR) 与数据流，集成 @tanstack/react-query-next-experimental。

• 支持一等公民级的 Suspense 集成，实现声明式的加载状态与数据获取。

• 最适合使用 React 18+ 且需要高性能数据同步与背景重新获取的项目。

• 使用此技能通过执行提供的 codemod 命令来进行自动导入更新，以迁移遗留实作。

• 输入通常包含 API 端点定义与数据获取函数；输出则是为您特定架构需求所配置的结构化 React Hooks。

• 请注意，v5 的个别 Hook 已移除 onSuccess、onError 和 onSettled 回调；请利用全局 queryCache 处理器来避免重复执行副作用。

• 请确保严格遵守所提供的“服务器 vs 客户端”配置对照表，以优化 SSR 环境中的边界情况处理。