Refine项目Auth Provider从3.x.x迁移到4.x.x指南

Refine项目Auth Provider从3.x.x迁移到4.x.x指南

refine 一个用于构建内部工具、管理面板、仪表盘和B2B应用程序的React框架，具有无与伦比的灵活性。 项目地址: https://gitcode.com/gh_mirrors/re/refine

前言

Refine作为一个强大的React框架，在4.x.x版本中对认证提供者(Auth Provider)进行了重大改进。本文将详细介绍如何从3.x.x版本迁移到4.x.x版本，帮助开发者理解这些变化背后的设计理念，并顺利完成迁移工作。

认证提供者变更背景

在Refine 4.x.x版本中，我们对认证提供者进行了重构，主要出于以下几个考虑：

1. 提升灵活性：新的设计允许处理更广泛的用例，同时保持接口简洁
2. 标准化接口：统一的方法签名提高了代码的可读性和可维护性
3. 错误处理改进：不再使用Promise.reject来处理业务错误，而是通过返回对象中的success标志来区分成功与失败状态
4. 重定向控制：移除了默认的重定向行为，开发者可以更精确地控制认证流程

核心变更概览

1. 接口重命名

首先，我们来看最基础的类型名称变更：

- import { AuthProvider } from "@refinedev/core";
+ import { AuthBindings } from "@refinedev/core";

- const authProvider: AuthProvider = {/* ... */}
+ const authProvider: AuthBindings = {/* ... */}

这一变更反映了新版本更加专注于绑定认证逻辑到应用中的设计理念。

2. 方法名称变更

多个方法名称进行了调整，使其更加语义化：

• getUserIdentity → getIdentity
• checkError → onError
• checkAuth → check
• useAuthenticated钩子 → useIsAuthenticated

3. 响应格式标准化

所有认证方法现在都遵循统一的响应格式：

type AuthActionResponse = {
  success: boolean;  // 操作是否成功
  redirectTo?: string;  // 重定向路径(可选)
  error?: Error;  // 错误对象(可选)
  [key: string]: unknown;  // 其他自定义属性
};

这种标准化使得代码更加一致，便于理解和调试。

详细迁移指南

登录(login)方法迁移

const authProvider = {
    login: async ({ email, password }) => {
        const user = mockUsers.find((item) => item.email === email);

        if (user) {
            localStorage.setItem("auth", JSON.stringify(user));
-           return Promise.resolve();
+           return {
+               success: true,
+               redirectTo: "/",
+           };
        }

-       return Promise.reject();
+       return {
+           success: false,
+           error: {
+               message: "Login Error",
+               name: "Invalid email or password",
+           }
+       };
    },
}

关键变化：

1. 总是返回Promise.resolve
2. 通过success字段表示操作结果
3. 显式指定redirectTo来控制重定向
4. 错误信息通过error字段传递

登出(logout)方法迁移

const authProvider = {
    logout: async () => {
        localStorage.removeItem("auth");
-       return Promise.resolve();
+       return {
+          success: true,
+          redirectTo: "/login",
+       };
    },
}

注意：现在需要显式指定登出后的重定向路径。

身份检查(check)方法迁移

原checkAuth方法更名为check，并改变了响应格式：

const authProvider = {
-   checkAuth: async () => {
+   check: async () => {
        const user = localStorage.getItem("auth");

        if (user) {
-           return Promise.resolve();
+           return {
+               authenticated: true,
+           };
        }

-       return Promise.reject();
+       return {
+           authenticated: false,
+           redirectTo: "/login",
+           logout: true,
+           error: {
+               message: "Check failed",
+               name: "User not found",
+           }
+       };
    },
};

新的响应类型为：

type CheckResponse = {
  authenticated: boolean;  // 是否已认证
  redirectTo?: string;    // 重定向路径
  logout?: boolean;       // 是否触发登出
  error?: Error;          // 错误信息
};

错误处理(onError)方法迁移

原checkError方法更名为onError：

const authProvider = {
-   checkError: async (error) => {
+   onError: async (error) => {
        if (error.status === 401 || error.status === 403) {
-           return Promise.reject();
+           return {
+               redirectTo: "/login",
+               logout: true,
+               error: error,
+           };
        }

-       return Promise.reject();
+       return {};
    },
};

钩子使用变更

认证相关的钩子也进行了相应调整。以下是认证组件的变化示例：

v3版本：

import { useAuthenticated } from "@pankod/refine-core";

export const Authenticated: React.FC = ({ children }) => {
  const { isSuccess, isLoading, isError } = useAuthenticated();

  if (isLoading) return <div>loading...</div>;
  if (isError) return null;
  if (isSuccess) return <>{children}</>;
  return null;
};

v4版本：

import { useIsAuthenticated } from "@refinedev/core";

export const Authenticated: React.FC = ({ children }) => {
  const { isLoading, data } = useIsAuthenticated();

  if (isLoading) return <div>loading...</div>;
  if (data.error) return null;
  if (data.authenticated) return <>{children}</>;
  return null;
};

主要变化：

1. 钩子名称从useAuthenticated变为useIsAuthenticated
2. 返回值结构变化，通过data对象访问认证状态
3. 错误状态现在通过data.error判断

向后兼容方案

为了平滑过渡，Refine 4.x.x仍然支持v3版本的authProvider，但需要做一些调整：

- import { AuthProvider } from "@refinedev/core";
+ import { LegacyAuthProvider } from "@refinedev/core";

- const authProvider: AuthProvider = {/* ... */}
+ const authProvider: LegacyAuthProvider = {/* ... */}

const App = () => {
    return (
        <Refine
-           authProvider={authProvider}
+           legacyAuthProvider={authProvider}
        >
            <AppLayout />
        </Refine>
    );
};

同时，在使用认证钩子时需要添加兼容标记：

import { useLogin } from "@refinedev/core";

const login = useLogin({
  v3LegacyAuthProviderCompatible: true,
});

最佳实践建议

1. 逐步迁移：对于大型项目，可以考虑逐步迁移，先使用兼容模式，再逐个模块更新
2. 错误处理：充分利用新的错误处理机制，为用户提供更友好的错误信息
3. 重定向控制：合理设计认证流程中的重定向逻辑，确保用户体验流畅
4. 类型安全：充分利用TypeScript类型检查，确保迁移后的代码符合新规范

总结

Refine 4.x.x对认证提供者的改进带来了更清晰的设计和更强大的灵活性。虽然迁移需要一些工作，但这些变化将为应用带来更好的可维护性和扩展性。通过本文的指南，开发者可以系统地完成迁移工作，并充分利用新版本提供的各种优势。

refine 一个用于构建内部工具、管理面板、仪表盘和B2B应用程序的React框架，具有无与伦比的灵活性。 项目地址: https://gitcode.com/gh_mirrors/re/refine