SuperAPI AI 工具集

router-core/type-safety

通用与其它

查看项目

更新于 10-16 00:00

技能介绍

本技能面向 TanStack Router 的类型安全实践。核心原则是路由参数、搜索参数、context 与 loader 数据均通过路由树自动推断,因此不要对已推断值添加类型注解、as 断言或显式泛型,断言会掩盖真实类型错误并破坏推断链。同时不要把 TanStack Router 与 Next.js、React Router 混淆:没有 getServerSideProps、useSearchParams(),也不从 react-router-dom 导入。

唯一必需的注解是 Register 模块声明:在创建 router 后用 declare module '@tanstack/react-router' 注册 router 类型,否则 Link、useNavigate、useSearch 等顶层导出失去类型安全。注册后各路由钩子自动推断类型;context 通过 createRootRouteWithContext 沿路由树流动。

钩子与 Link 使用 from 收窄到具体路由,避免返回全部路由的联合类型;跨路由共享组件用 strict:false。代码分割的懒加载文件用 getRouteApi 而非直接导入 Route。

性能方面:大型路由树用对象语法写 addChildren;loader 不返回未被消费的复杂推断类型;Link 选项对象用 as const satisfies LinkProps 而非把变量标注为 LinkProps;自定义组件可用 ValidateLinkOptions、ValidateNavigateOptions、ValidateRedirectOptions 保持调用点收窄,或用 render props 让 Link 在调用处收窄。select 与 structuralSharing 可优化重渲染,后者仅支持 JSON 兼容数据。常见错误包括添加类型注解或断言、使用未收窄的 LinkProps、未用 from 收窄、漏写 Register 注册、以及误用其他框架的导入和文件结构。

示例代码与安装命令本资料未提供。适用范围限于使用 TanStack Router 的 React 项目。