Refine v4 发布深度解读企业级路由、全新 AuthProvider 与全自动 codemod 迁移【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refineRefine v4 是 Refine一个用于构建内部工具、管理后台、仪表盘与 B2B 应用的 React 框架在 v3 发布一年后的重大版本更新围绕更灵活的接入方式、更小的打包体积、更一致的开发体验对核心 API 进行了重构。本文以官方发布公告为主体结合当前仓库中的 codemod 源码、迁移指南与核心类型定义系统梳理 v4 的六大关键变化新的refinedevNPM 组织、可插拔的routerProvider、以路径定义 action 的企业级路由、移除 re-export 后的体积优化、统一返回success键的新版authProvider接口以及一键自动升级的refine3-to-refine4codemod读完即可掌握从 v3 平滑升级到 v4 的完整路线。版本背景为什么要发布 v4自 v3 发布一年以来Refine 团队收集了社区中最受关注的需求与疑问v4 的核心理念是更优秀的开发者体验DX引入新的抽象与技术帮助开发者管理数据data、路由routing、鉴权authorization、布局layouts等横切关注点同时不限制开发者使用其他工具和库平台全覆盖让 Refine 能够在所有支持 React 的平台上运行并可以无缝集成进新项目与既有项目100% 向后兼容v4 承诺完全向后兼容用户可以放心升级应用行为不会意外改变全量 codemod 支持整个升级过程可以自动完成无需手动修改文件。在仓库中可以看到这一目标的实际落地证据packages/codemod目录从 v1 到 v5 的迁移转换器一应俱全packages/codemod/src/transformations其中refine3-to-refine4.ts正是 v4 升级的核心转换器。新 NPM 组织从pankod到refinedevRefine 迁移到了新的 NPM 组织refinedev所有包名随之更新。更新前的旧包名pankod/refine-*与 v4 新包名的对照关系如下旧包名新包名pankod/refine-corerefinedev/corepankod/refine-clirefinedev/clipankod/refine-inferencerrefinedev/inferencerpankod/refine-antdrefinedev/antdpankod/refine-muirefinedev/muipankod/refine-mantinerefinedev/mantinepankod/refine-chakra-uirefinedev/chakra-uipankod/refine-react-hook-formrefinedev/react-hook-formpankod/refine-react-tablerefinedev/react-tablepankod/refine-react-router-v6refinedev/react-router-v6pankod/refine-nextjs-routerrefinedev/nextjs-routerpankod/refine-remixrefinedev/remixpankod/refine-strapi-v4refinedev/strapi-v4pankod/refine-simple-restrefinedev/simple-restpankod/refine-appwriterefinedev/appwritepankod/refine-supabaserefinedev/supabasepankod/refine-airtablerefinedev/airtablepankod/refine-hasurarefinedev/hasurapankod/refine-graphqlrefinedev/graphqlpankod/refine-medusarefinedev/medusapankod/refine-nestjsx-crudrefinedev/nestjsx-crudpankod/refine-ablyrefinedev/ablypankod/refine-kbarrefinedev/kbar如果选择手动迁移需要先卸载所有pankod包再安装对应的refinedev包npm uninstall pankod/refine-core pankod/refine-antd pankod/.. npm i refinedev/core refinedev/antd refinedev/..注意必须对所有以pankod开头的包执行这一替换操作。仓库中的 codemod 源码印证了这一替换逻辑在 packages/codemod/src/transformations/v4/replace-pankod-imports-with-refinedev.ts 中previousScope被定义为pankod/refine-newScope为refinedev/转换器会遍历ImportDeclaration与ExportNamedDeclaration将源码中所有pankod/refine-前缀替换为refinedev/同时把旧包名登记到待卸载列表、新包名登记到待安装列表交给后置流程统一处理依赖。唯一的例外是pankod/refine-react-location与pankod/refine-react-router这两个被标记为废弃的包不会被自动迁移。Bring your own router路由与框架彻底解耦v4 对routerProvider进行了重新设计将路由彻底从 Refine 中解耦出来。新的routerProvider只承担Refine 与路由器之间的连接器这一单一职责不再规定路由的声明方式。这意味着Refine 可以接入 Next.js、Remix 等企业级路由平台获得无缝的开发体验开发者可以把 Refine 集成进已有项目无需修改现有路由或应用结构这也为将来支持 React Native 等平台打下了基础。从当前仓库核心类型可以看到 v4 之后routerProvider的最终形态packages/core/src/contexts/router/types.tsexport type RouterProvider { go?: () GoFunction; back?: () BackFunction; parse?: () ParseFunction; Link?: React.ComponentType React.PropsWithChildren{ to: string; [prop: string]: any } ; };整个 Provider 仅由go编程式导航、back回退、parse解析当前 URL 为 resource/action/id/params 等结构化信息、Link路由链接组件四个成员组成路由声明方式完全交由用户所选的 Router 决定实现了真正的自带路由器BYOR。为了保持向后兼容v3 的routerProvider被更名为legacyRouterProvider保留- import routerProvider from pankod/refine-react-router-v6; import routerProvider from refinedev/react-router-v6/legacy; const App () { return ( Refine - routerProvider{routerProvider} legacyRouterProvider{routerProvider} / ); };迁移指南明确提示虽然旧接口可用但不推荐长期使用因为新的routerProvider接口支持嵌套路由带参数、自定义 action 路由等更强大的能力。从 packages/codemod/src/transformations/v4/router-to-legacy-router.ts 可以看出codemod 正是负责自动完成这类routerProvider到legacyRouterProvider的改名操作。企业级路由用路径定义 action自由构造多租户路由配合新的routerProviderv4 对resources属性也做了重大调整。过去resources对路由系统是必需的现在它更像应用与 API 之间的连接点路由可以在没有resources的情况下工作resources也可以在路由缺席的情况下工作。最关键的变化是list、create、edit、show、clone这些 action 现在可以直接声明为路径字符串而不是组件resources{[ { name: products, list: /:tenantId/products, show: /:tenantId/products/:id, edit: /:tenantId/products/:id/edit, create: /:tenantId/products/create, } ]}这种声明方式带来了两个直接收益完全自定义 action 路由不再受限于 Refine 自动生成的固定路由可以充分利用所选 Router 的全部能力天然支持多租户结构如上例所示:tenantId等动态参数可以直接内嵌到资源路径中配合 hooks 与组件中的meta属性传递参数即可轻松实现多租户应用的租户隔离式路由。在构造导航路径时URL 中已有的参数也会被自动沿用。需要注意的是这只是一个资源定义真正的路由匹配仍需在 Router 结构中处理。精简打包体积移除 re-export 的包为了优化性能与打包体积v4 移除了 Refine 中的 re-export 包。社区反馈表明对于依赖 Remix、Next.js 构建各类 CRUD 应用的 React 框架来说bundle size 越来越重要。移除 re-export 后应用可以达到与原生 React 项目相同的打包体积。以refinedev/antd为例改造前Button、Form、Input等组件是从 Refine 的 antd 包中再导出的v4 之后Refine 只保留自己封装的 hook 与组件UI 组件直接来自antd本体- import { useTable, SaveButton, Button, Form, Input } from pankod/refine-antd; import { useTable, SaveButton } from refinedev/antd; import { Button, Form, Input } from antd;受此影响的包包括refinedev/antdrefinedev/muirefinedev/chakra-uirefinedev/mantinerefinedev/react-hook-formrefinedev/react-table此外Icons也从refinedev/antd中移除需要改为从ant-design/icons直接导入npm install ant-design/icons- import { Icons } from pankod/refine-antd; import { UserOutlined } from ant-design/icons;从 codemod 源码可以看到这套拆分逻辑的自动化实现packages/codemod/src/transformations/v4/separate-imports-antd.ts转换器依据 packages/codemod/src/definitions/separated-imports/antd.ts 中的映射表把pankod/refine-antd中属于antd的组件拆分到独立的antd导入语句把Icons命名空间导入替换为来自ant-design/icons的导入并在安装依赖阶段自动补充antd^5.0.5与ant-design/icons^5.0.1同时会在图标导入处自动加上注释建议使用显式命名导入import { IconName } from ant-design/icons以进一步减小打包体积。值得注意的是v4 对应的 antd 版本从 4.x 升级到了 5.xcodemod 在运行refine3-to-refine4前会先检查项目中的 antd 版本packages/codemod/src/helpers/check-antd-version-is-3x.ts如果仍在使用 antd 4会提示先通过antd4-to-antd5转换器完成 antd 升级后再继续。新的 AuthProvider统一返回success键v4 为authProvider的方法引入了统一的返回接口目标是提升透明度、方便调试。旧版的做法是authProvider方法成功时 resolve、失败时 reject。这种模式有局限性——reject 通常与错误/异常绑定而对登录凭据不正确这类非异常性质的失败而言用 reject 表达会造成语义混淆也妨碍调试。v4 之后authProvider的方法始终返回一个 resolve 的 Promise其值为一个包含success键的对象success指示操作是否成功失败时可通过可选的error键携带一个Error对象来通知用户。这一接口设计在当前仓库核心类型中有完整呈现packages/core/src/contexts/auth/types.tsexport type AuthActionResponse { success: boolean; redirectTo?: string; error?: RefineError | Error; [key: string]: unknown; successNotification?: SuccessNotificationResponse; }; export type AuthProvider { login: (params: any) PromiseAuthActionResponse; logout: (params: any) PromiseAuthActionResponse; check: (params?: any) PromiseCheckResponse; onError: (error: any) PromiseOnErrorResponse; register?: (params: any) PromiseAuthActionResponse; forgotPassword?: (params: any) PromiseAuthActionResponse; updatePassword?: (params: any) PromiseAuthActionResponse; getPermissions?: (params?: Recordstring, any) PromisePermissionResponse; getIdentity?: (params?: any) PromiseIdentityResponse; };login、logout、register等返回AuthActionResponse其核心就是success: booleancheck返回CheckResponse以authenticated: boolean为主键并可通过redirectTo、logout等字段表达未认证时跳转到哪里、是否登出的细粒度语义onError返回OnErrorResponse。从类型源码中的设计注释可以推断这种总是 resolve、用结构化字段表达结果的模式正是为了覆盖未认证但不登出登出但不跳转跳转到非 /login 页面等各种组合场景同时便于在 hooks如useLogout之间传递跳转等参数。这意味着 v4 中一个典型的login实现可以写成const authProvider { login: async ({ email, password }) { const result await api.login(email, password); if (result.ok) { return { success: true, redirectTo: / }; } return { success: false, error: new Error(Invalid credentials), }; }, // ... };codemod 中对应的authProvider-to-legacyAuthProvider转换器packages/codemod/src/transformations/v4/authProvider-to-legacyAuthProvider.ts会把旧式resolve/reject 风格的authProvider迁移为legacyAuthProvider配合add-v3LegacyAuthProviderCompatible-true-to-auth-hooks为认证 hooks 添加v3LegacyAuthProviderCompatible: true选项保证旧项目在过渡期内的行为一致。用 refine-codemod 一键完成 v3 → v4 迁移为了终结耗时数小时的手动升级Refine 从很早的版本起就用 codemod 管理所有破坏性变更。v4 的迁移只需在项目根目录package.json所在位置执行一条命令npx refinedev/codemodlatest refine3-to-refine4命令执行完毕后项目即升级为refine4.x.x。得益于完整的 codemod 支持包名替换、import 拆分、废弃 API 改名等所有破坏性变更都会自动完成。从仓库源码可以还原这条命令背后的完整工作流。refine3-to-refine4转换器packages/codemod/src/transformations/refine3-to-refine4.ts在源码转换阶段依次执行fixV4Deprecations修复 v4 中标记废弃的 APIseparateImportsReactRouterV6/separateImportsAntD/separateImportsChakra/separateImportsMantine/separateImportsMUI/separateImportsReactHookForm/separateImportsReactQuery/separateImportsReactTable按映射表拆分各 UI 库的 re-exportaddV3LegacyAuthProviderCompatibleTrueToAuthHooks为认证 hooks 加入旧版兼容开关authProviderToLegacyAuthProvider将旧式 authProvider 改为 legacyAuthProvidermetaDataToMeta将metaData重命名为metamoveDeprecatedAccessControlProps/resourceNameToResourceForButtons/routerToLegacyRouter/useMenuToCore处理 access control 属性迁移、resourceName改名、routerProvider 迁移、useMenu 引入来源迁移replacePankodImportsWithRefineDev全局替换pankod/refine-前缀为refinedev/。随后进入postTransform后置阶段读取项目package.json把所有pankod/refine-*依赖替换为对应的refinedev/*依赖其中 MUI 包会被固定到可迁移版本^4.18.2其余为latest检测到pankod/refine-cli时自动替换为refinedev/cli最后依据yarn.lock/package-lock.json的检测结果自动执行安装。运行入口packages/codemod/src/index.ts还提供了--force绕过 Git 安全检查、--dry试运行不修改文件、--print打印转换结果等选项。已知限制来自迁移指南 documentation/versioned_docs/version-4.xx.xx/migration-guide/3x-to-4x.md包含 TypeScript 实例化表达式Instantiation Expressions或.d.ts类型声明文件的文件可能无法被正确解析需要手动迁移codemod 生成的 React Fragment.../返回语句可能需要手动重新格式化。变更清单与升级路线总览本次 v4 涉及组件与 hooks 更新的包及其变更明细均可在此次迁移的相关文档中找到refinedev/corerefinedev/antdrefinedev/muirefinedev/mantinerefinedev/chakra-uirefinedev/react-tablerefinedev/react-hook-formrefinedev/react-router-v6refinedev/nextjs-routerrefinedev/remix仓库内的完整迁移指南位于 documentation/versioned_docs/version-4.xx.xx/migration-guide/3x-to-4x.md其中覆盖了上述全部破坏性变更的手动操作步骤与refinedev/codemod的推荐用法如果你想观察 v4 时代各包的真实用法可以直接阅读 examples 目录下各示例项目的package.json与源码——它们统一采用refinedev/*命名空间是验证升级结果的最佳参照。总结Refine v4 的发布是框架架构层面的重要演进新的refinedevNPM 组织统一了包命名全量 codemod 让包名替换零成本routerProvider瘦身为纯粹的路由连接器路由声明完全交给开发者选择的 RouterNext.js、Remix 等平台得以无缝接入resources支持以路径定义 action解锁了嵌套路由与多租户参数等企业级路由能力移除 re-export 包使应用体积与原生 React 项目持平新的authProvider接口以success键统一表达结果让鉴权逻辑更透明、更易调试refine3-to-refine4codemod将数小时的迁移工作压缩为一条命令配合 100% 向后兼容与legacyRouterProvider/legacyAuthProvider过渡通道开发者可以按自己的节奏完成升级。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考