剖析 WordPress `register_rest_route()` 函数的源码：如何通过 `permission_callback` 参数控制权限。

各位观众，晚上好！我是今天的主讲人，江湖人称“代码老司机”。咱们今天不飙车，来聊聊WordPress的权限控制，特别是register_rest_route()函数里的permission_callback参数。

开场白：REST API与权限的爱恨情仇

话说江湖上，WordPress的REST API就像一块肥肉，谁都想咬一口。但问题来了，谁能咬？咬多少？这就得靠权限控制了。想象一下，如果没有权限控制，随便一个阿猫阿狗都能把你网站的数据扒个精光，那还得了？

register_rest_route()函数是注册REST API endpoint的关键，而permission_callback就是守门员，决定谁能通过，谁只能吃闭门羹。

第一章：register_rest_route()函数概览

在深入permission_callback之前，我们先简单回顾一下register_rest_route()函数。它的基本语法如下：

register_rest_route( string $namespace, string $route, array $args = array(), bool $override = false )

• $namespace: API的命名空间，通常是my-plugin/v1之类的。
• $route: API的路由，比如/posts或者/comments/(?P<id>d+)。
• $args: 一个包含各种参数的数组，其中就包括我们今天要重点讨论的permission_callback。
• $override: 是否覆盖已存在的路由。

$args数组里，最重要的几个参数包括：

参数名称	作用
methods	指定允许的HTTP方法，比如GET、POST、PUT、DELETE。
callback	处理请求的回调函数。
permission_callback	权限检查的回调函数，决定是否允许访问该endpoint。
args	定义请求参数，并对参数进行验证和过滤。

今天，咱们主要聚焦在permission_callback这个参数上。

第二章：permission_callback的庐山真面目

permission_callback是一个回调函数，它的作用是检查当前用户是否有权限访问这个REST API endpoint。 这个函数接收一个WP_REST_Request对象作为参数，并返回一个布尔值：

• true: 允许访问。
• false: 拒绝访问。

如果返回false，WordPress会返回一个401 Unauthorized错误。

重点来了！

permission_callback的回调函数必须符合以下格式：

function my_permission_check( WP_REST_Request $request ) {
  // 在这里进行权限检查
  if ( /* 检查条件 */ ) {
    return true; // 允许访问
  } else {
    return false; // 拒绝访问
  }
}

第三章：permission_callback的常见用法，案例分析

接下来，我们通过几个实际的例子，来看看permission_callback的常见用法。

案例一：只有登录用户才能访问

这是最简单的权限控制，只需要检查用户是否已经登录。

function my_plugin_check_if_user_logged_in() {
    return is_user_logged_in();
}

add_action( 'rest_api_init', function () {
    register_rest_route( 'my-plugin/v1', '/logged-in-data', array(
        'methods'  => 'GET',
        'callback' => 'my_plugin_get_logged_in_data',
        'permission_callback' => 'my_plugin_check_if_user_logged_in',
    ) );
});

function my_plugin_get_logged_in_data() {
    return array( 'message' => 'Hello, logged-in user!' );
}

在这个例子中，my_plugin_check_if_user_logged_in()函数使用is_user_logged_in()函数来判断用户是否已经登录。只有登录用户才能访问/my-plugin/v1/logged-in-data这个endpoint，未登录用户会收到401错误。

案例二：只有管理员才能访问

有些API endpoint只能让管理员访问，比如设置网站选项之类的。

function my_plugin_check_if_user_is_admin() {
    return current_user_can( 'administrator' );
}

add_action( 'rest_api_init', function () {
    register_rest_route( 'my-plugin/v1', '/admin-only-data', array(
        'methods'  => 'GET',
        'callback' => 'my_plugin_get_admin_only_data',
        'permission_callback' => 'my_plugin_check_if_user_is_admin',
    ) );
});

function my_plugin_get_admin_only_data() {
    return array( 'message' => 'Hello, administrator!' );
}

这里，my_plugin_check_if_user_is_admin()函数使用current_user_can( 'administrator' )函数来判断当前用户是否具有administrator权限。

案例三：基于特定能力（capability）的权限控制

WordPress的权限系统非常灵活，可以自定义能力。比如，我们可以创建一个manage_my_plugin能力，只有具有这个能力的用户才能访问某个endpoint。

function my_plugin_check_if_user_can_manage_plugin() {
    return current_user_can( 'manage_my_plugin' );
}

add_action( 'rest_api_init', function () {
    register_rest_route( 'my-plugin/v1', '/plugin-management', array(
        'methods'  => 'POST', // 假设这是一个用来管理插件的endpoint
        'callback' => 'my_plugin_manage_plugin',
        'permission_callback' => 'my_plugin_check_if_user_can_manage_plugin',
    ) );
});

function my_plugin_manage_plugin( WP_REST_Request $request ) {
    // 处理插件管理逻辑
    return array( 'message' => 'Plugin managed successfully!' );
}

// 在插件激活时，给管理员添加自定义能力
register_activation_hook( __FILE__, function() {
    $role = get_role( 'administrator' );
    $role->add_cap( 'manage_my_plugin' );
});

// 在插件禁用时，移除自定义能力
register_deactivation_hook( __FILE__, function() {
    $role = get_role( 'administrator' );
    $role->remove_cap( 'manage_my_plugin' );
});

这个例子稍微复杂一些。首先，我们定义了一个manage_my_plugin能力。然后在插件激活时，将这个能力添加到管理员角色。在插件禁用时，将这个能力移除。my_plugin_check_if_user_can_manage_plugin()函数使用current_user_can( 'manage_my_plugin' )函数来判断当前用户是否具有这个能力。

案例四：基于请求参数的权限控制

有时候，权限的判断需要基于请求的参数。比如，只有作者才能编辑自己的文章。

function my_plugin_check_if_user_can_edit_post( WP_REST_Request $request ) {
    $post_id = $request->get_param( 'id' ); // 从请求中获取文章ID
    $post = get_post( $post_id );

    if ( ! $post ) {
        return new WP_Error( 'post_not_found', 'Post not found.', array( 'status' => 404 ) );
    }

    if ( get_current_user_id() == $post->post_author ) {
        return true; // 允许访问
    } else {
        return false; // 拒绝访问
    }
}

add_action( 'rest_api_init', function () {
    register_rest_route( 'my-plugin/v1', '/posts/(?P<id>d+)', array(
        'methods'  => 'PUT',
        'callback' => 'my_plugin_update_post',
        'permission_callback' => 'my_plugin_check_if_user_can_edit_post',
        'args' => array(
            'id' => array(
                'validate_callback' => 'is_numeric',
                'sanitize_callback' => 'absint',
                'required' => true,
            ),
        ),
    ) );
});

function my_plugin_update_post( WP_REST_Request $request ) {
    $post_id = $request->get_param( 'id' );
    // 更新文章的逻辑
    return array( 'message' => 'Post updated successfully!' );
}

在这个例子中，my_plugin_check_if_user_can_edit_post()函数从WP_REST_Request对象中获取文章ID，然后判断当前用户是否是该文章的作者。

案例五：使用非WordPress内置的权限系统

有些项目可能会使用非WordPress内置的权限系统，例如使用JWT (JSON Web Tokens) 进行身份验证。在这种情况下，permission_callback 可以用来验证 JWT token 的有效性。

function my_plugin_check_jwt_token( WP_REST_Request $request ) {
    $token = $request->get_header( 'Authorization' ); // 从header中获取token

    if ( empty( $token ) ) {
        return false; // 没有token，拒绝访问
    }

    // 这里需要调用你的JWT验证函数，验证token的有效性
    $is_valid = my_plugin_validate_jwt( $token );

    if ( $is_valid ) {
        return true; // token有效，允许访问
    } else {
        return false; // token无效，拒绝访问
    }
}

function my_plugin_validate_jwt( $token ) {
    // 验证 JWT Token 的逻辑，这部分代码会根据你的JWT库而变化
    // 这只是一个示例，你需要根据你的实际情况进行修改
    try {
        $decoded = FirebaseJWTJWT::decode($token, new Key(YOUR_SECRET_KEY, 'HS256'));
        return true;
    } catch (Exception $e) {
        return false;
    }
}

add_action( 'rest_api_init', function () {
    register_rest_route( 'my-plugin/v1', '/jwt-protected-data', array(
        'methods'  => 'GET',
        'callback' => 'my_plugin_get_jwt_protected_data',
        'permission_callback' => 'my_plugin_check_jwt_token',
    ) );
});

function my_plugin_get_jwt_protected_data() {
    return array( 'message' => 'Hello, JWT authenticated user!' );
}

这个例子中，我们假设使用 JWT 进行身份验证。my_plugin_check_jwt_token() 函数从请求的header中获取 JWT token，然后调用 my_plugin_validate_jwt() 函数验证 token 的有效性。如果 token 有效，则允许访问，否则拒绝访问。 这个例子使用了 firebase/php-jwt 库，你需要先通过 composer 安装这个库: composer require firebase/php-jwt. 并且替换 YOUR_SECRET_KEY 为你的实际密钥.

第四章：WP_REST_Request对象：信息的宝库

在permission_callback函数中，WP_REST_Request对象是至关重要的。它包含了所有关于当前请求的信息，包括：

• get_params(): 获取所有请求参数。
• get_param( $param_name ): 获取指定名称的请求参数。
• get_headers(): 获取所有请求header。
• get_header( $header_name ): 获取指定名称的请求header。
• get_body(): 获取请求的body内容。
• get_method(): 获取HTTP方法（GET, POST, PUT, DELETE等）。

利用这些信息，我们可以在permission_callback函数中进行各种复杂的权限判断。

第五章：错误处理：优雅地拒绝访问

如果permission_callback函数返回false，WordPress会默认返回一个401 Unauthorized错误。但是，有时候我们需要更详细的错误信息，或者自定义错误代码。

我们可以通过返回一个WP_Error对象来实现自定义错误处理。

function my_plugin_check_permission_with_custom_error() {
    if ( /* 检查条件 */ ) {
        return true;
    } else {
        return new WP_Error( 'permission_denied', 'You do not have permission to access this resource.', array( 'status' => 403 ) );
    }
}

在这个例子中，如果权限检查失败，我们返回一个WP_Error对象，包含错误代码permission_denied，错误信息You do not have permission to access this resource.，以及HTTP状态码403 Forbidden。

第六章：性能优化：避免不必要的权限检查

权限检查是耗时的操作，特别是在高流量的网站上。因此，我们需要尽量避免不必要的权限检查。

• 缓存权限检查结果： 如果权限检查的结果在一段时间内不会改变，可以考虑将结果缓存起来，避免重复检查。
• 使用正确的HTTP方法： 对于只读操作，应该使用GET方法，而不是POST方法。这样可以减少不必要的权限检查。
• 尽量减少permission_callback中的逻辑： permission_callback函数应该只负责权限检查，而不是其他业务逻辑。

第七章：安全注意事项：防止权限绕过

权限控制是安全的关键，必须小心谨慎，防止权限绕过。

• 不要依赖客户端的权限判断： 客户端的权限判断很容易被篡改，必须在服务器端进行权限检查。
• 验证所有请求参数： 请求参数可能包含恶意代码，必须进行验证和过滤。
• 使用HTTPS： HTTPS可以防止中间人攻击，保护数据的安全。
• 定期审查代码： 定期审查代码可以发现潜在的安全漏洞。

总结：permission_callback，权限控制的瑞士军刀

permission_callback是WordPress REST API权限控制的核心。通过灵活运用permission_callback，我们可以实现各种复杂的权限控制需求，保护网站的数据安全。 希望今天的讲座对大家有所帮助。记住，代码的世界，安全第一！下次有机会，我们再聊其他话题。 祝大家晚安！