router-query-integration

此技能为整合 TanStack Router 与 TanStack Query 提供了系统性的方法，专为构建高性能单页应用程序（SPA）的开发人员而设计。核心目标是将数据获取从组件渲染阶段转移到路由加载器（loader）阶段，有效地消除请求串联（waterfalls）并提高感知的性能。通过在导航生命周期中利用查询预取（prefetching），此技能确保在路由组件挂载时已准备好关键数据，从而实现瞬间导航体验。

• 通过 ensureQueryData、prefetchQuery 和 fetchQuery 方法，实现路由加载器与查询客户端之间的精确协作。

• 支持复杂的数据需求，包括多个查询的并行获取，以及需要先验证路由参数的序列化依赖查询。

• 通过使用 Query Options 模式促进强类型安全性，确保在功能模块与路由之间实现 DRY（不要重复自己）的代码编写。

• 提供稳健的错误处理模式，允许开发人员在路由加载器中捕获加载失败，并通过标准的 Router 错误边界进行显示。

• 包含查询失效与缓存管理的最佳实践，特别是在处理变更（mutations）以确保整个应用程序的数据一致性时。

• 为 QueryClient 提供优化的配置模式，以微调 staleTime 和 gcTime，从而获得更好的缓存性能。

• 适用于使用 React 与 TanStack 生态系统库的前端工程师，他们需要优化复杂的导航流程。

• 预期的输入包括路由定义、查询键（query keys）定义以及 API 获取函数。

• 主要产出为一个强健且具备类型安全的数据加载架构，保证在组件渲染前数据已可用。

• 限制条件包括确保 QueryClient 单例可供路由模块导入，并确保加载器逻辑保持纯净，以支持服务器端渲染（SSR）与导航中断。

• 建议在应用程序根目录实现 QueryClientProvider，以实现路由、查询缓存与 React 树之间的无缝整合。