router-query-integration

Router × Query Integration 技能是为 React 开发人员设计的专业工作流组件，专注于构建高效能单页应用 (SPA)。此技能解决了消除请求瀑布流 (request waterfalls) 并提升路由转换时感知效能的挑战，通过将路由级数据获取与全局查询状态管理同步来达成目标。它主要针对使用 TanStack Router 和 TanStack Query 的团队，提供标准化且具备类型安全的数据编排方案。通过在组件渲染前使用路由加载器 (loaders) 启动数据获取，用户可确保导航过程流畅，同时保有缓存去重与 stale-while-revalidate 模式的优势。此技能涵盖了多种实现策略，从简单的查询预获取到复杂的相依请求与并行加载，并确保通过整合路由器错误边界与 suspense 组件实现稳健的错误处理。

• 使用 ensureQueryData、prefetchQuery 与 fetchQuery 模式实现路由级数据预获取。

• 利用路由加载器内的 Promise.all 实现数据并行加载，以最大化导航期间的处理效率。

• 通过 Query Options 模式 (queryOptions) 强化类型安全与代码重复利用。

• 管理相依查询，处理后续数据请求依赖于先前加载器数据的场景。

• 提供变更 (mutation) 后手动清除缓存的模式，确保 UI 状态与服务器保持同步。

• 支持开发阶段除错，协助自动挂载 Router 与 Query Client 的开发者工具。

• 输入包括 React 路由定义、现有的 TanStack Query 客户端，以及用于数据获取的 API 服务函数。

• 输出包含优化的加载器配置与查询整合模式，旨在最小化请求延迟。

• 开发人员应集中定义查询键 (query keys) 以确保应用程序整体的缓存一致性。

• 当页面渲染必须依赖数据时，建议使用 ensureQueryData 以防止不必要的重复获取。

• 利用 staleTime 配置来平衡数据新鲜度需求与网络性能。

• 务必将路由级加载器与组件层中的 React Query hooks 搭配使用，以维护对即时数据状态与后台自动更新功能的访问。