深入理解 WordPress `rest_authorization_required` 钩子源码：如何自定义 REST API 的授权检查。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位程序猿/媛们，大家好！今天咱们来聊聊 WordPress REST API 的授权，特别是那个神秘又重要的 rest_authorization_required 钩子。别怕，咱们不搞学院派那一套，就用大白话和实战代码，把这玩意儿扒个精光！

开场白：REST API 的门卫大爷

想象一下，WordPress REST API 就是一个豪华小区，里面的数据资源是住户，而未经授权的访问，就相当于想溜进小区偷东西的坏人。我们当然不能让坏人得逞，所以小区门口必须有个门卫大爷，负责检查每个人的身份。

rest_authorization_required 钩子，就是这个门卫大爷！它会在每个 REST API 请求到达真正处理逻辑之前，拦截请求，判断请求者是否有权限访问。如果没有权限，就直接轰出去，维护小区的安全。

rest_authorization_required 钩子：一个简单的介绍

这个钩子是一个过滤器 (filter)，这意味着你可以挂载一个函数到这个钩子上，来修改它的默认行为。默认情况下，WordPress 会检查当前用户是否已登录。如果没有登录，它会返回一个错误，提示需要授权。

钩子名称: rest_authorization_required
参数: $result (mixed): 授权结果。如果之前的过滤器已经返回了一个错误，那么这个参数就是这个错误对象。否则，它就是 true。
返回值: mixed: 如果允许访问，返回 true。如果拒绝访问，返回一个 WP_Error 对象。

默认的门卫大爷：is_user_logged_in()

WordPress 默认的授权检查逻辑，其实很简单，就是调用 is_user_logged_in() 函数。如果用户已登录，就放行；否则，就拦住。

// 默认的授权检查逻辑 (简化版)
add_filter( 'rest_authorization_required', function ( $result ) {
    if ( ! is_user_logged_in() ) {
        return new WP_Error(
            'rest_not_logged_in',
            __( 'You are not currently logged in.' ),
            array( 'status' => 401 )
        );
    }

    return $result; // 允许访问
});

这段代码的意思是：

我们往 rest_authorization_required 钩子上挂载了一个匿名函数。
这个匿名函数首先检查用户是否登录 (is_user_logged_in())。
如果没登录，就创建一个 WP_Error 对象，包含错误码、错误信息和 HTTP 状态码（401，未授权）。
如果登录了，就直接返回 $result，也就是 true，表示允许访问。

自定义你的门卫大爷：实战演练

现在，我们来玩点高级的，自定义一个门卫大爷，让它能根据不同的条件，决定是否允许访问。

场景 1：只有特定角色的用户才能访问

假设我们有一个自定义的 REST API 接口，只想让管理员 (administrator) 和编辑 (editor) 角色的用户才能访问。

add_filter( 'rest_authorization_required', function ( $result ) {
    if ( ! is_user_logged_in() ) {
        return new WP_Error(
            'rest_not_logged_in',
            __( 'You are not currently logged in.' ),
            array( 'status' => 401 )
        );
    }

    $user = wp_get_current_user();
    $allowed_roles = array( 'administrator', 'editor' );

    if ( ! array_intersect( $allowed_roles, $user->roles ) ) {
        return new WP_Error(
            'rest_forbidden',
            __( 'You do not have permission to access this resource.' ),
            array( 'status' => 403 )
        );
    }

    return $result; // 允许访问
});

这段代码的解释：

首先，我们检查用户是否登录。如果没登录，就直接返回错误。
然后，我们获取当前用户信息 (wp_get_current_user())。
定义一个允许访问的角色列表 ($allowed_roles)。
使用 array_intersect() 函数，检查用户的角色是否在允许访问的角色列表中。如果不在，就返回一个 WP_Error 对象，提示没有权限（HTTP 状态码 403，禁止访问）。

场景 2：根据请求参数进行授权

有时候，我们需要根据请求参数来判断是否允许访问。例如，我们有一个 REST API 接口，用于更新文章，但只允许作者本人才能更新。

add_filter( 'rest_authorization_required', function ( $result ) {
    // 获取当前请求的 REST 路由信息
    $request = rest_get_current_request();
    $route = $request->get_route();

    // 只针对特定的路由进行授权检查 (假设我们的文章更新接口是 /wp/v2/posts/{id})
    if ( strpos( $route, '/wp/v2/posts/' ) === 0 ) {
        // 获取文章 ID
        $post_id = $request->get_param( 'id' );

        // 确保文章 ID 是一个数字
        if ( ! is_numeric( $post_id ) ) {
            return new WP_Error(
                'invalid_post_id',
                __( 'Invalid post ID.' ),
                array( 'status' => 400 )
            );
        }

        // 获取文章信息
        $post = get_post( $post_id );

        // 确保文章存在
        if ( ! $post ) {
            return new WP_Error(
                'post_not_found',
                __( 'Post not found.' ),
                array( 'status' => 404 )
            );
        }

        // 检查用户是否登录
        if ( ! is_user_logged_in() ) {
            return new WP_Error(
                'rest_not_logged_in',
                __( 'You are not currently logged in.' ),
                array( 'status' => 401 )
            );
        }

        // 获取当前用户 ID
        $user_id = get_current_user_id();

        // 检查当前用户是否是文章的作者
        if ( (int) $post->post_author !== (int) $user_id ) {
            return new WP_Error(
                'rest_forbidden',
                __( 'You are not the author of this post.' ),
                array( 'status' => 403 )
            );
        }
    }

    return $result; // 允许访问 (或者交给其他的过滤器处理)
});

这段代码比较复杂，我们来逐步分析：

获取请求信息: rest_get_current_request() 函数可以获取当前的 REST 请求对象，通过这个对象，我们可以获取请求的路由、参数等信息。
路由判断: 我们只针对特定的路由 (例如 /wp/v2/posts/{id}) 进行授权检查。这样可以避免影响其他的 REST API 接口。
获取文章 ID: 通过 $request->get_param( 'id' ) 获取文章 ID。
数据验证: 确保文章 ID 是一个数字，并且文章存在。
登录检查: 检查用户是否登录。
作者验证: 获取当前用户 ID，并检查当前用户是否是文章的作者。

场景 3：使用 Capabilities 进行授权

WordPress 的 Capabilities 机制，可以更灵活地控制用户的权限。例如，我们可以创建一个自定义的 Capability，然后只允许拥有这个 Capability 的用户访问 REST API 接口。

首先，我们需要定义一个自定义的 Capability。可以在主题的 functions.php 文件或者自定义插件中添加以下代码：

function my_custom_register_capabilities() {
    // 获取管理员角色
    $admin_role = get_role( 'administrator' );

    // 添加自定义 Capability
    $admin_role->add_cap( 'my_custom_access_rest_api' );

    // 你也可以给其他角色添加这个 Capability，例如 editor
    $editor_role = get_role( 'editor' );
    $editor_role->add_cap( 'my_custom_access_rest_api' );
}
add_action( 'init', 'my_custom_register_capabilities' );

这段代码会在 WordPress 初始化时，给管理员和编辑角色添加一个名为 my_custom_access_rest_api 的 Capability。

然后，我们可以使用 current_user_can() 函数来检查用户是否拥有这个 Capability。

add_filter( 'rest_authorization_required', function ( $result ) {
    if ( ! current_user_can( 'my_custom_access_rest_api' ) ) {
        return new WP_Error(
            'rest_forbidden',
            __( 'You do not have permission to access this resource.' ),
            array( 'status' => 403 )
        );
    }

    return $result; // 允许访问
});

WP_Error 对象：授权失败的返回值

当授权失败时，我们需要返回一个 WP_Error 对象。这个对象包含以下信息：

属性	描述
`$code`	错误码，一个字符串，用于唯一标识错误类型。
`$message`	错误信息，一个字符串，用于描述错误原因。
`$data`	额外的数据，一个数组，可以包含一些额外的信息，例如 HTTP 状态码。

一些需要注意的点：

优先级: rest_authorization_required 钩子可以被多次调用，所以你需要注意过滤器的优先级。可以使用 add_filter() 函数的第三个参数来指定优先级。
性能: 授权检查逻辑应该尽可能简单高效，避免影响 REST API 的性能。
安全: 授权检查逻辑要足够安全，防止未经授权的访问。
错误处理: 当授权失败时，要返回清晰的错误信息，方便客户端进行调试。
针对性: 授权检查逻辑应该尽可能针对特定的 REST API 接口，避免过度限制。

高级技巧：使用中间件（Middleware）

虽然 rest_authorization_required 钩子已经很强大了，但如果你的授权逻辑非常复杂，可以考虑使用中间件模式。中间件是一个函数，它在请求到达处理逻辑之前被执行，可以进行各种处理，例如授权、日志记录、数据验证等。

你可以创建一个自定义的中间件类，然后将授权逻辑封装到这个类中。

class My_REST_API_Middleware {
    public function authorize( WP_REST_Request $request ) {
        // 授权逻辑
        if ( ! is_user_logged_in() ) {
            return new WP_Error(
                'rest_not_logged_in',
                __( 'You are not currently logged in.' ),
                array( 'status' => 401 )
            );
        }

        return true; // 允许访问
    }
}

// 在 REST API 路由注册时，指定中间件
add_action( 'rest_api_init', function () {
    register_rest_route( 'my-plugin/v1', '/my-resource', array(
        'methods'  => 'GET',
        'callback' => 'my_rest_api_callback',
        'permission_callback' => array( new My_REST_API_Middleware(), 'authorize' ), // 使用中间件进行授权
    ) );
} );

function my_rest_api_callback( WP_REST_Request $request ) {
    // 处理 REST API 请求
    return 'Hello, world!';
}

在这个例子中，我们创建了一个 My_REST_API_Middleware 类，其中包含一个 authorize 方法，用于进行授权检查。在注册 REST API 路由时，我们将 permission_callback 参数设置为 array( new My_REST_API_Middleware(), 'authorize' )，这样 WordPress 就会在调用 my_rest_api_callback 函数之前，先执行 authorize 方法。

总结：打造坚固的 REST API 防火墙

rest_authorization_required 钩子是 WordPress REST API 安全的关键组成部分。通过自定义这个钩子的行为，我们可以实现各种复杂的授权逻辑，保护我们的数据资源。希望通过今天的讲解，大家能够对 rest_authorization_required 钩子有更深入的理解，并能够灵活运用它，打造坚固的 REST API 防火墙。

记住，安全无小事，授权要谨慎！代码写的好，Bug 才能少！

发表回复 取消回复

发表回复取消回复