Refine v5 路由迁移指南从routerProvider3.x 到 4.x 的全面升级实践【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine导读本文以 Refine 官方迁移文档为主体系统讲解从 Refine v3.x 的routerProvider路由提供器迁移到 v4.x/v5 新式路由绑定的全过程包括变更动机、Refine组件 props 的废弃、认证与权限控制的职责转移、以及 React Router v6 / Remix / Next.js 三种主流路由方案的实操接入方式。读完本文你将掌握新路由架构下的useLink、useGo、useBack、useParsed四个核心 hook能够在不改造成本项目既有路由结构的前提下将 Refine 无缝集成进现有应用。变更动机把路由交还给开发者Refine 对routerProvider和路由处理的改造核心动机是提升灵活性与易用性。官方文档明确指出通过把routerProvider简化为 Refine 与路由器之间的“交互与连接点”Refine 不再规定定义路由的特定方式也不再强制要求必须传入routerProvider——这使 Refine 能够满足企业级应用的多样化需求。这一设计取向在源码中得到了直接印证。路由绑定类型定义 中RouterProvider的四个成员go、back、parse、Link全部被标记为可选并附有一段关键的实现注释我们将这些函数定义为可选某些功能可能无法正常工作但这是有意的。用户可以选择使用路由绑定也可以不使用或者使用自己的路由绑定。把控制权留给用户是最佳方式。这解释了为什么此次迁移的核心收益是你可以在不修改当前路由或应用结构的情况下将 Refine 集成进现有项目——继续像以前一样使用路由器同时享受 Refine 提供的数据、表单、表格等能力。重要注意事项迁移前必须知道的三件事1. 认证检查不再由路由接管使用新版routerProvider后路由层不再内置认证拦截。如果应用使用了authProvider你需要自行负责认证检查官方推荐两种方式useIsAuthenticatedhook命令式Authenticated组件声明式包装器具体实现示例可在 Authenticated 组件文档 和各示例应用中查看。2. 访问控制检查同样需要自行处理与认证流程类似路由内部不再处理权限控制。你需要使用useCanhook 或CanAccess组件自行完成可参考 CanAccess 组件文档。3. 路由的创建与控制完全交由用户你必须手动创建路由如果希望资源操作create/edit/list/show 等使用特定路径可以将路径传入resources数组中对应 action。文档中虽然提供了从资源生成路由的方法但它们是可选的且不推荐使用因为这会限制灵活性。Refine组件的 props 变化由于路由处理已从Refine组件中解耦组件接受的 props 也随之改变已废弃且不再生效的布局类 propsLayout、Sider、Title、Header、Footer、OffLayoutArea。不过UI 包导出的这些组件仍然受到良好支持你可以在创建路由和页面时在应用内部使用它们。同样废弃的组件 propsDashboardPage、catchAll、LoginPage。你需要自己创建对应的路由和页面来替代。旧版行为提示Dashboard 页面由于DashboardPageprop 已废弃你需要为 dashboard 创建自己的 index 路由。可以将该项加入resources数组使其出现在Sider菜单中——useMenu会根据resources数组生成菜单项你也可以用useMenuhook 自行定制菜单。错误页面和登录页面同理用你的路由器所适配的方式自行创建替代原先catchAll和LoginPageprops 的职责。自定义Sider组件的迁移如果你曾从 UI 包 swizzle 出Sider组件并做过定制在使用新的routerProviderprop 时可能需要同步更新。更新useRouterContext的使用新版routerProvider引入后v3 兼容的路由提供器改由legacyRouterProviderprop 提供如果使用legacyRouterProvideruseRouterContext会继续照常工作如果使用新版routerProvideruseRouterContext对你而言已废弃且无用可以轻松替换为useLink、useGo、useBack、useParsed这四个路由 hook。在Sider组件中Refine 曾通过useRouterContext获取Link组件。迁移时既可以改用useLinkhook也可以直接切换到路由器自身的Link实现如react-router-dom的Link或next/link- import { useRouterContext } from refinedev/core; import { useLink } from refinedev/core; const CustomSider () { - const { Link } useRouterContext(); const Link useLink(); /* ... */ }注意如果你定制过useMenuhook 的使用方式请检查其表现是否符合预期。虽然useMenu的返回值没有改变但它生成菜单项 key 的方式已经变化。路由行为的变更由于 Refine 不再内部创建路由你可以不受任何限制地按照自己的框架创建路由。authentication与access control从 Refine 中解耦应按照你的框架惯例处理。同时Refine 提供了一组辅助工具让这些任务更易完成Authenticated组件作为包装器或useIsAuthenticatedhook —— 用于认证CanAccess组件作为包装器或useCanhook —— 用于访问控制新路由提供器的底层原理要理解迁移后的使用方式有必要先看清新版routerProvider的契约。核心类型定义在 packages/core/src/contexts/router/types.ts成员签名职责go() GoFunction导航到指定路由接收GoConfig含to、query、hash、type、keepQuery/keepHash选项back() BackFunction返回上一路由无参数缺失时 UI 包可能隐藏返回按钮parse() ParseFunction解析当前路由、查询参数引导 Refine 识别出正确的resource、action、id及paramsLinkReact.ComponentType渲染内部链接的组件其中GoConfig.type支持push | replace | path三种模式——path模式仅返回拼接好的路径字符串而不执行导航这在需要只构造链接的场景下非常实用。以 React Router v6 绑定为例bindings.tsx 展示了每个成员的典型实现go从useLocation读取现有search与hash通过qs合并查询参数支持keepQuery/keepHash最终调用useNavigate执行导航back直接映射为navigate(-1)parse调用matchResourceFromRoute(pathname, resources)从当前路径匹配出resource与action再合并useParams与 query string并将currentPage、pageSize数值化、id解码最终输出结构完整的ParseResponse。四个新 hook从useNavigation到细分职责类型注释中说明了一个关键设计转变不再使用单一的useNavigationhook我们将这些函数拆分为三个不同的 hookuseGo、useBack和useParsed连同useLink共四个。它们的实现位于 packages/core/src/hooks/routeruseGo在go之上增加了按资源导航的能力。当config.to传入{ resource, action, id, meta }对象时会通过useGetToPath自动计算出资源操作对应的真实路径若该action未在资源上定义、或edit/show/clone缺少id会抛出带明确提示的错误。useBack从RouterContext取出back函数供返回按钮使用。useParsed用useMemo缓存parse()的结果返回当前路由解析出的{ resource, action, id, params, pathname }。useLink返回全局Link组件使自定义 Sider 等内部组件无需感知具体路由器实现。误用检测checkRouterPropMisuse新版架构还内置了防呆机制。check-router-prop-misuse 会检查routerProviderprop 中除go、parse、back、Link之外的属性一旦发现存在其他属性典型场景是把 v3 风格的routes等旧配置塞进新 prop会console.warn提示你可能想使用legacyRouterProviderprop 替代。这能帮助迁移过程中的开发者快速定位问题。使用新路由提供器三种主流方案Refine 为每种提供绑定的路由器都编写了独立文档以下是最常用的三种。React Router v6如果你使用react-router-dom和refinedev/react-router-v6需要使用Routes、Route、Outlet等组件生成路由用你选定的路由器包裹Refine组件如BrowserRouter从refinedev/react-router-v6导入routerProvider传给Refine在resources数组中为资源操作指定路径。⚠️ 已知问题partial segments部分分段已移除Refine 原先依赖react-router-dom6.3.0现已升级到react-router-domlatest。由于6.5.0版本移除了 partial segment 支持你自定义路由中形如profile/:username/:page的写法将无法按预期工作需要按如下方式更新Refine - routerProvider{{ - ...routerProvider, - routes: [ - { - element: ProfilePage /, - path: profile/:username/:page, }, ], }} routerProvider{routerProvider} Route pathprofile/:username/:page element{ProfilePage /} / /Refine- Link toprofile/:username/:page / Link toprofile/:username/:page /详细的接入说明可查看refinedev/react-router-v6包文档 及仓库中的实际示例如 examples/with-remix-headless 之外的 examples/with-nextjs-headless、examples/base-headless 等基于 React Router 的 headless 示例应用。Remix 与 Next.js如果使用 Remix 或 Next.js步骤为首先按照你惯常的方式使用基于文件系统的路由file system-based routing创建路由将refinedev/remix-router或refinedev/nextjs-router提供的routerProvider传给Refine组件在resources数组中指定资源操作的路径。仓库中提供了可直接对照的完整示例examples/with-remix-antd、examples/with-remix-material-ui、examples/with-nextjs、examples/with-nextjs-next-auth 等均演示了如何在文件系统路由之上接入 Refine 资源。分别参考refinedev/remix-router与 Remix 官方文档对应示例见 with-remix-headlessrefinedev/nextjs-router与 Next.js 官方文档对应示例见 with-nextjs迁移检查清单检查项旧方式新方式路由创建Refine 内部根据routes/catchAll等生成完全由你或你的框架创建认证拦截路由层自动处理useIsAuthenticated/Authenticated访问控制路由层自动处理useCan/CanAccessDashboardRefine DashboardPage{...}自建 index 路由 加入resources错误/登录页catchAll/LoginPageprops自建路由与页面布局 propsLayout/Sider/Header/Footer/OffLayoutArea废弃改在路由树中自行组装组件获取 LinkuseRouterContext().LinkuseLink或路由器原生Link旧版兼容—legacyRouterProviderv3 绑定继续可用总结Refine v5 的路由架构将路由定义权完整交还给开发者routerProvider只保留go、back、parse、Link四个轻量绑定点认证、权限、页面组织全部由你的框架与组件自行掌控同时通过legacyRouterProvider保证 v3 时代的平滑过渡用checkRouterPropMisuse帮助开发者识别新旧 prop 混用。迁移路径清晰——按 React Router v6 / Remix / Next.js 三种方案创建路由、替换四个 hook、补充认证与权限检查即可在保留既有路由结构的前提下完整获得 Refine 的能力。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
