分析 WordPress `rest_api_init` 钩子源码：此钩子在何时被触发，以及其在 REST API 初始化中的作用。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，晚上好！咳咳，今天咱们来聊聊WordPress里一个相当重要，但可能被很多人忽略的钩子：rest_api_init。别看名字长，其实它在WordPress REST API的世界里扮演着一个关键的角色，相当于REST API大厦的地基。

一、咱们先来“望文生义”一下：rest_api_init是个啥？

顾名思义，rest_api_init就是“REST API 初始化”的意思。它是一个action hook，允许我们在WordPress启动REST API时执行一些自定义操作。可以理解为： “嘿，哥们，REST API要开始工作了，你要不要搞点事情？”

二、 rest_api_init在什么时候“蹦出来”？

要理解rest_api_init的触发时机，咱们得先看看WordPress启动REST API的流程。其实这事儿藏在WordPress的核心代码里，具体位置在wp-includes/rest-api.php文件里。

咱们简化一下，大概的流程是这样的：

WordPress启动： 整个系统开始运作。
parse_request action hook: WordPress解析HTTP请求，看看是不是REST API的请求。
rest_api_loaded action hook: REST API的核心类被加载。
rest_api_init action hook: 就在这里！ rest_api_init被触发，允许你注册自定义路由，定义权限校验规则，等等。

为了更直观，咱们写个简单的代码片段模拟一下 (注意：这只是演示，实际代码更复杂)：

// 假设这是 WordPress 核心代码的某个部分
function maybe_load_rest_api() {
  // 检查是否是 REST API 请求 (简化版)
  if ( is_rest_api_request() ) {
    // 加载 REST API 核心类
    require_once ABSPATH . 'wp-includes/rest-api.php';

    // 触发 rest_api_init 钩子
    do_action( 'rest_api_init' );
  }
}

// 假设这是判断是否是 REST API 请求的函数 (简化版)
function is_rest_api_request() {
  // 实际的判断逻辑更复杂，这里只是个示例
  return ( isset( $_SERVER['REQUEST_URI'] ) && strpos( $_SERVER['REQUEST_URI'], '/wp-json/' ) !== false );
}

// 在 WordPress 初始化时尝试加载 REST API
add_action( 'init', 'maybe_load_rest_api' );

总结一下： rest_api_init在init action hook之后，并且在REST API核心类被加载后触发。也就是说，它是REST API启动过程中的一个关键节点。

三、 rest_api_init到底能干啥？

rest_api_init的主要作用就是让你“插手”REST API的配置。常见的用法包括：

注册自定义路由 (Registering Custom Routes): 这是最常见的用途。你可以用它来定义自己的API端点，比如获取特定类型的数据，或者执行特定的操作。
定义权限校验规则 (Defining Permissions): 你可以控制哪些用户可以访问你的API端点，以及他们可以执行哪些操作。
修改REST API的响应 (Modifying Responses): 你可以添加自定义字段，或者改变数据的格式。
注册自定义数据类型 (Registering Custom Data Types): 你可以让REST API支持你的自定义数据类型，比如自定义文章类型或者自定义字段。

咱们来举几个例子：

1. 注册自定义路由：

假设你想创建一个API端点，用来获取所有标题包含 "WordPress" 的文章。

add_action( 'rest_api_init', 'register_custom_route' );

function register_custom_route() {
  register_rest_route(
    'myplugin/v1', // 命名空间，建议使用插件名称
    '/posts/wordpress', // 路由路径
    array(
      'methods'  => 'GET', // 请求方法
      'callback' => 'get_wordpress_posts', // 回调函数
      'permission_callback' => '__return_true', // 权限校验，这里允许所有人访问
    )
  );
}

function get_wordpress_posts( $request ) {
  $args = array(
    's' => 'WordPress', // 搜索关键词
    'post_type' => 'post', // 文章类型
    'posts_per_page' => -1, // 获取所有文章
  );

  $posts = get_posts( $args );

  // 处理数据，只返回标题
  $data = array();
  foreach ( $posts as $post ) {
    $data[] = array(
      'id' => $post->ID,
      'title' => $post->post_title,
    );
  }

  return rest_ensure_response( $data ); // 确保返回的是 REST API 响应对象
}

这段代码做了以下事情：

add_action( 'rest_api_init', 'register_custom_route' );：告诉WordPress，在rest_api_init触发时，执行register_custom_route函数。
register_rest_route()：这是WordPress提供的函数，用来注册REST API路由。
- 'myplugin/v1'：命名空间，用于区分不同的插件或主题的API端点。建议使用插件或主题的名称。
- '/posts/wordpress'：路由路径，也就是API端点的URL。例如：http://your-site.com/wp-json/myplugin/v1/posts/wordpress
- array(...)：包含路由的配置信息。
  - 'methods' => 'GET'：指定允许的HTTP请求方法，这里是GET。
  - 'callback' => 'get_wordpress_posts'：指定处理请求的回调函数，这里是get_wordpress_posts。
  - 'permission_callback' => '__return_true'：指定权限校验的回调函数。 __return_true 表示允许所有人访问。如果你需要更复杂的权限校验，可以自定义一个函数。
get_wordpress_posts()：这个函数负责处理请求，并返回数据。
- 它使用get_posts()函数获取所有标题包含 "WordPress" 的文章。
- 然后，它将文章数据处理成一个包含ID和标题的数组。
- 最后，它使用rest_ensure_response()函数将数据转换为REST API响应对象。

2. 定义权限校验规则：

假设你只想让管理员访问你的API端点。

add_action( 'rest_api_init', 'register_custom_route' );

function register_custom_route() {
  register_rest_route(
    'myplugin/v1',
    '/admin-only',
    array(
      'methods'  => 'GET',
      'callback' => 'get_admin_data',
      'permission_callback' => 'is_user_admin', // 权限校验，只有管理员才能访问
    )
  );
}

function get_admin_data( $request ) {
  // 只有管理员才能执行的代码
  return rest_ensure_response( array( 'message' => 'Hello, Admin!' ) );
}

function is_user_admin() {
  return current_user_can( 'administrator' ); // 检查当前用户是否是管理员
}

在这个例子中，permission_callback被设置为is_user_admin函数。这个函数使用current_user_can( 'administrator' )来检查当前用户是否是管理员。如果不是管理员，REST API将返回一个401错误。

3. 修改REST API的响应：

假设你想在REST API的响应中添加一个自定义字段，比如网站的描述。

add_filter( 'rest_prepare_post', 'add_site_description_to_post', 10, 3 );

function add_site_description_to_post( $response, $post, $request ) {
  $response->data['site_description'] = get_bloginfo( 'description' );
  return $response;
}

这段代码使用rest_prepare_post filter hook来修改文章的REST API响应。它将网站的描述添加到response->data数组中。

四、 rest_api_init的注意事项

命名空间 (Namespace): 使用命名空间来避免与其他插件或主题的API端点冲突。
权限校验 (Permissions): 一定要对你的API端点进行权限校验，防止未经授权的访问。
数据验证 (Data Validation): 对API的输入数据进行验证，防止恶意数据破坏你的系统。
错误处理 (Error Handling): 优雅地处理错误，并返回清晰的错误信息。
性能优化 (Performance Optimization): 尽量减少API的请求次数，并使用缓存来提高性能。

五、总结和一些“骚操作”

rest_api_init钩子是WordPress REST API的一个重要组成部分。它可以让你自定义REST API的行为，注册自定义路由，定义权限校验规则，等等。掌握rest_api_init钩子的用法，可以让你更好地利用WordPress REST API，构建强大的应用程序。

来点“骚操作”：

动态路由： 你可以使用正则表达式来定义更灵活的路由。例如，你可以创建一个路由来获取所有指定分类的文章： /posts/category/(?P<category_slug>[a-zA-Z0-9-]+)。
版本控制： 你可以使用命名空间来进行版本控制。例如，你可以创建myplugin/v1和myplugin/v2两个命名空间，分别对应不同的API版本。
批量操作： 你可以创建一个API端点来执行批量操作，例如批量更新文章或者批量删除评论。

六、咱们来个表格总结一下：

钩子名称	触发时机	主要作用	示例代码
`rest_api_init`	`init` action hook之后，并且在REST API核心类被加载后触发	1. 注册自定义路由 (Registering Custom Routes) 2. 定义权限校验规则 (Defining Permissions) 3. 修改REST API的响应 (Modifying Responses) 4. 注册自定义数据类型 (Registering Custom Data Types)	`add_action( 'rest_api_init', 'register_custom_route' );` `function register_custom_route() { register_rest_route( 'myplugin/v1', '/posts/wordpress', array( 'methods' => 'GET', 'callback' => 'get_wordpress_posts', 'permission_callback' => '__return_true', ) ); }`
`rest_prepare_post`	在文章数据被格式化为REST API响应之前触发	允许你修改文章的REST API响应。例如，你可以添加自定义字段，或者改变数据的格式。	`add_filter( 'rest_prepare_post', 'add_site_description_to_post', 10, 3 );` `function add_site_description_to_post( $response, $post, $request ) { $response->data['site_description'] = get_bloginfo( 'description' ); return $response; }`

七、最后“皮”一下：

各位观众老爷，今天的讲座就到这里。希望大家能够掌握rest_api_init钩子的用法，并在WordPress REST API的世界里“为所欲为”！记住，编程的乐趣在于不断探索和创新，不要害怕犯错，大胆尝试，你总会发现新的惊喜！祝大家编码愉快！ (鞠躬)

发表回复 取消回复

发表回复取消回复