详解 WordPress `rest_authorization_required` 钩子源码：如何自定义 REST API 的授权检查。

大家好，欢迎来到今天的“WordPress REST API 防狼术：rest_authorization_required 钩子深度解析”讲座！

今天咱们不聊风花雪月，只聊如何给你的 WordPress REST API 穿上防弹衣，防止不怀好意的人随便闯入。核心武器就是 rest_authorization_required 钩子。准备好了吗？系好安全带，发车了！

一、API 安全：你的数据你做主

想象一下，你的 WordPress 站点是一个金库，里面的数据就是你的金银珠宝。REST API 就像金库的大门，谁都可以通过它来访问你的数据。如果没有安全措施，岂不是谁都能进来搬东西？

这就是为什么 API 安全至关重要。我们需要确保只有经过授权的人才能访问特定的 API 端点。而 rest_authorization_required 钩子，就是我们设置访问权限的一把瑞士军刀。

二、rest_authorization_required：守门大爷的眼神

rest_authorization_required 钩子就像一个经验丰富的守门大爷，站在每个 REST API 请求的入口处，仔细地检查每个人的身份。它在 WordPress 核心验证用户是否已经登录之后触发，但 在 执行实际的 API 处理之前。 换句话说，它决定了请求 能否 继续。

这个钩子允许你自定义授权逻辑。你可以根据自己的需求，定义哪些用户可以访问哪些 API 端点。

三、源码剖析：看看大爷的工具箱

我们来扒一扒 rest_authorization_required 钩子的源码，看看它到底是怎么工作的。虽然不用你全部记住，但了解一下总没坏处。

WordPress 核心中，rest_authorization_required 钩子通常在 WP_REST_Server::dispatch() 方法中被触发。简化后的代码如下：

// 在 WP_REST_Server 类中
public function dispatch( $request ) {
    // ... 一些准备工作 ...

    // 检查是否需要授权
    $requires_auth = $this->check_authentication();

    if ( is_wp_error( $requires_auth ) ) {
        return $requires_auth;
    }

    if ( $requires_auth ) {
        // 触发 rest_authorization_required 钩子
        $result = apply_filters( 'rest_authorization_required', true, $request );

        if ( ! $result ) {
            return new WP_Error(
                'rest_forbidden',
                __( 'Sorry, you are not allowed to do that.' ),
                array( 'status' => rest_authorization_required_code() )
            );
        }
    }

    // ... 继续处理请求 ...
}

这段代码的核心在于：

1. $this->check_authentication(): 检查用户是否已经通过了基本的身份验证（例如，是否登录）。
2. apply_filters( 'rest_authorization_required', true, $request ): 这行代码就是触发 rest_authorization_required 钩子的地方。
   • 第一个参数 'rest_authorization_required' 是钩子的名称。
   • 第二个参数 true 是默认返回值。这意味着，如果没有人注册这个钩子，或者注册的钩子都返回 true，那么请求就会被允许。
   • 第三个参数 $request 是 WP_REST_Request 对象，包含了所有关于请求的信息，比如 URL、参数、请求方法等等。

重点来了： 如果你注册的函数返回 false 或者一个 WP_Error 对象，那么请求就会被拒绝，并返回一个 "Sorry, you are not allowed to do that." 的错误信息。

四、实战演练：自定义授权逻辑

现在，让我们来写一些代码，看看如何使用 rest_authorization_required 钩子来实现自定义的授权逻辑。

场景一：只有管理员才能访问某个 API 端点

假设我们有一个 API 端点，用于管理站点设置。我们只想让管理员才能访问这个端点。

add_filter( 'rest_authorization_required', 'my_custom_authorization', 10, 2 );

function my_custom_authorization( $allowed, $request ) {
    // 获取请求的路由
    $route = $request->get_route();

    // 如果请求的路由是 '/myplugin/v1/settings'，则进行授权检查
    if ( '/myplugin/v1/settings' === $route ) {
        // 检查当前用户是否是管理员
        if ( ! current_user_can( 'manage_options' ) ) {
            return new WP_Error(
                'rest_forbidden',
                __( '只有管理员才能访问此端点。' ),
                array( 'status' => rest_authorization_required_code() )
            );
        }
    }

    // 如果不是指定的路由，则允许访问
    return $allowed;
}

代码解释：

1. add_filter( 'rest_authorization_required', 'my_custom_authorization', 10, 2 ): 将 my_custom_authorization 函数注册到 rest_authorization_required 钩子上。
   • 10 是优先级，数字越小，优先级越高。
   • 2 是传递给回调函数的参数个数（$allowed 和 $request）。
2. $route = $request->get_route(): 获取请求的路由。例如，/myplugin/v1/settings。
3. if ( '/myplugin/v1/settings' === $route ): 判断当前请求是否是我们要保护的 API 端点。
4. if ( ! current_user_can( 'manage_options' ) ): 使用 WordPress 内置的 current_user_can() 函数检查当前用户是否具有 manage_options 权限（管理员权限）。
5. return new WP_Error(...): 如果用户不是管理员，则返回一个 WP_Error 对象，拒绝访问。
6. return $allowed: 如果不是指定的路由，或者用户是管理员，则返回 $allowed，也就是 true (默认值)，允许访问。

场景二：根据自定义的元数据进行授权

有时候，我们需要根据用户或帖子的自定义元数据来进行授权。例如，我们可能只想让某个帖子的作者才能更新该帖子。

add_filter( 'rest_authorization_required', 'my_custom_post_authorization', 10, 2 );

function my_custom_post_authorization( $allowed, $request ) {
    // 获取请求的路由
    $route = $request->get_route();

    // 如果请求的路由是 '/wp/v2/posts/(?P<id>[d]+)'，则进行授权检查
    if ( preg_match( '#^/wp/v2/posts/(?P<id>[d]+)$#', $route, $matches ) ) {
        // 获取帖子 ID
        $post_id = $request['id'];

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

        // 获取帖子的作者 ID
        $post_author_id = get_post_field( 'post_author', $post_id );

        // 检查当前用户是否是帖子的作者
        if ( $current_user_id != $post_author_id ) {
            return new WP_Error(
                'rest_forbidden',
                __( '只有帖子的作者才能更新此帖子。' ),
                array( 'status' => rest_authorization_required_code() )
            );
        }
    }

    // 如果不是指定的路由，则允许访问
    return $allowed;
}

代码解释：

1. preg_match( '#^/wp/v2/posts/(?P<id>[d]+)$#', $route, $matches ): 使用正则表达式匹配请求的路由。这个正则表达式匹配的是 WordPress 默认的帖子 API 端点，其中 (?P<id>[d]+) 表示匹配一个数字，并将其命名为 id。
2. $post_id = $request['id']: 从请求参数中获取帖子 ID。
3. $post_author_id = get_post_field( 'post_author', $post_id ): 使用 get_post_field() 函数获取帖子的作者 ID。
4. if ( $current_user_id != $post_author_id ): 检查当前用户 ID 是否与帖子的作者 ID 相等。
5. 如果用户不是帖子的作者，则拒绝访问。

场景三：基于 API 密钥的授权

有时候，我们可能需要使用 API 密钥来进行授权。例如，我们可能想让第三方应用通过 API 密钥来访问我们的 API。

add_filter( 'rest_authorization_required', 'my_custom_api_key_authorization', 10, 2 );

function my_custom_api_key_authorization( $allowed, $request ) {
    // 获取 API 密钥
    $api_key = $request->get_header( 'X-API-Key' );

    // 检查 API 密钥是否有效
    if ( ! my_validate_api_key( $api_key ) ) {
        return new WP_Error(
            'rest_forbidden',
            __( '无效的 API 密钥。' ),
            array( 'status' => rest_authorization_required_code() )
        );
    }

    // 如果 API 密钥有效，则允许访问
    return $allowed;
}

// 自定义函数，用于验证 API 密钥
function my_validate_api_key( $api_key ) {
    // 在这里编写你的 API 密钥验证逻辑
    // 例如，从数据库中查找 API 密钥是否存在
    // 或者，使用加密算法验证 API 密钥是否有效

    // 示例：
    $valid_api_keys = array(
        'abcdefg123456',
        'hijklmnop789012',
    );

    return in_array( $api_key, $valid_api_keys );
}

代码解释：

1. $api_key = $request->get_header( 'X-API-Key' ): 从请求头中获取 API 密钥。我们假设 API 密钥是通过 X-API-Key 请求头传递的。
2. my_validate_api_key( $api_key ): 调用自定义的 my_validate_api_key() 函数来验证 API 密钥是否有效。
3. my_validate_api_key() 函数：
   • 这个函数需要你根据自己的需求来实现。
   • 你可以从数据库中查找 API 密钥是否存在。
   • 你也可以使用加密算法验证 API 密钥是否有效。
   • 在示例代码中，我们简单地将 API 密钥与一个预定义的 API 密钥列表进行比较。

五、最佳实践：安全第一，舒适第二

在使用 rest_authorization_required 钩子时，以下是一些最佳实践：

• 最小权限原则： 只授予用户访问他们需要的 API 端点的权限。不要让用户拥有过多的权限。
• 安全验证： 使用强密码、多因素身份验证等安全措施来保护你的用户账户。
• 输入验证： 验证所有来自用户的输入，防止 SQL 注入、XSS 攻击等安全漏洞。
• 错误处理： 在发生错误时，返回清晰的错误信息，方便用户调试。但不要暴露敏感信息。
• 日志记录： 记录所有 API 请求，方便你审计和排查问题。

六、总结：你的 API，你做主

rest_authorization_required 钩子是 WordPress REST API 安全的重要组成部分。通过自定义授权逻辑，你可以确保只有经过授权的人才能访问你的 API 端点。

希望今天的讲座能帮助你更好地保护你的 WordPress REST API。记住，安全第一，舒适第二。在构建 API 的时候，一定要把安全放在首位。

表格总结：rest_authorization_required 钩子详解

属性	说明
钩子名称	rest_authorization_required
触发时机	在 WordPress 核心验证用户登录后，但在 API 处理之前。
默认返回值	true (允许访问)
参数	$allowed (boolean, 默认 true)，$request (WP_REST_Request 对象)
返回值	true (允许访问)，false 或 WP_Error 对象 (拒绝访问)
应用场景	限制特定用户角色访问 API 端点，根据自定义元数据进行授权，使用 API 密钥进行授权，等等。
注意事项	遵循最小权限原则，进行安全验证，验证用户输入，返回清晰的错误信息，记录 API 请求。

最后的温馨提示：

• 代码示例仅供参考，你需要根据自己的实际需求进行修改。
• 在生产环境中使用之前，请务必进行充分的测试。
• 保持学习，不断提升自己的安全意识和技能。

好了，今天的讲座就到这里。感谢大家的参与！ 如果有问题，欢迎提问。 祝大家写出安全又强大的 WordPress REST API！我们下期再见！