深入理解 WordPress `rest_post_dispatch` 钩子源码：在 REST API 路由处理后执行自定义逻辑。

各位观众老爷，晚上好！今天咱们来聊聊 WordPress REST API 里一个相当有用的钩子：rest_post_dispatch。 简单来说，它就像是 REST API 这趟列车的终点站，你可以在这里做一些收尾工作，比如记录日志、修改返回结果，或者做一些其他的“善后”处理。

一、REST API 的“前世今生”和 rest_post_dispatch 的位置

咱们先简单回顾一下 WordPress REST API 的工作流程，方便大家理解 rest_post_dispatch 的重要性。

1. 请求来了！ (Request Arrives): 用户通过 HTTP 请求访问某个 API 接口，例如 /wp-json/wp/v2/posts/123。
2. 路由匹配 (Route Matching): WordPress 会根据请求的 URL，在注册的路由表中查找对应的处理函数。 路由表里定义了哪些 URL 对应哪些函数。
3. 权限验证 (Authentication & Authorization): 确认用户是否有权限访问这个 API。没权限？直接打回！
4. 参数处理 (Parameter Validation & Sanitization): 对请求参数进行验证和清理，确保数据的安全和正确性。
5. 业务逻辑处理 (Route Handler Execution): 执行注册的路由处理函数，这个函数负责完成具体的业务逻辑，比如获取文章数据、创建新文章等等。
6. 数据序列化 (Data Serialization): 将处理函数返回的数据转换成 JSON 格式，准备返回给客户端。
7. rest_post_dispatch 钩子触发 (rest_post_dispatch Hook Triggered): 在数据序列化 之后，返回给客户端 之前， rest_post_dispatch 钩子会被触发。 这就是我们今天的主角登场的地方。
8. 响应返回 (Response Sent): 将 JSON 格式的响应数据发送给客户端。

用一张表来总结一下：

阶段	描述	rest_post_dispatch 相关性
请求到达	用户发起 API 请求	无
路由匹配	WordPress 查找对应的处理函数	无
权限验证	验证用户权限	无
参数处理	验证和清理请求参数	无
业务逻辑处理	执行处理函数	无
数据序列化	将数据转换为 JSON 格式	无
rest_post_dispatch 钩子	执行自定义逻辑	核心！
响应返回	将 JSON 数据发送给客户端	无

二、rest_post_dispatch 钩子的源码探秘

我们来扒一扒 rest_post_dispatch 的源码，看看它到底长什么样。 虽然 WordPress 的源码可能看起来有点吓人，但别怕，咱们抽丝剥茧，慢慢分析。

在 wp-includes/rest-api/class-wp-rest-server.php 文件中，你可以找到 dispatch() 方法。这个方法负责处理 REST API 的请求。在 dispatch() 方法的末尾，你会看到如下代码：

/**
 * Filters the result of a REST API route before it is sent to the client.
 *
 * @since 4.7.0
 *
 * @param WP_REST_Response|mixed $result  Result of the route handler.
 * @param WP_REST_Server $server Server instance.
 * @param WP_REST_Request $request Request used to generate the response.
 *
 * @return WP_REST_Response Result of the route handler.
 */
$result = apply_filters( 'rest_post_dispatch', rest_ensure_response( $result ), $this, $request );

return rest_get_server()->response_to_data( $result, $request->get_param( '_fields', null ) );

这段代码做了两件事：

1. 应用 rest_post_dispatch 钩子: apply_filters( 'rest_post_dispatch', ...) 这行代码就是触发 rest_post_dispatch 钩子的关键。它会执行所有注册到这个钩子上的函数。
2. 转换为数据: rest_get_server()->response_to_data(...) 将最终的 WP_REST_Response 对象转换为可序列化的数据，准备返回给客户端。

重点：

• $result：这是路由处理函数返回的结果。它可以是 WP_REST_Response 对象，也可以是其他任何类型的数据。
• $this：这是 WP_REST_Server 类的实例，你可以用它来访问 REST API 服务器的一些信息。
• $request：这是 WP_REST_Request 对象，包含了请求的所有信息，比如 URL、参数、头部等等。

三、rest_post_dispatch 的用途：你能用它做什么？

rest_post_dispatch 钩子非常灵活，你可以用它来做很多事情。 让我们来看一些常见的应用场景：

1. 日志记录： 记录 API 请求的信息，比如请求的 URL、参数、响应时间等等。 方便你进行性能分析和故障排查。
2. 修改响应数据： 在数据返回给客户端之前，对响应数据进行修改。 例如，你可以添加一些额外的字段，或者对某些字段的值进行格式化。
3. 缓存控制： 设置 HTTP 缓存头部，控制客户端的缓存行为。 提高 API 的性能。
4. 安全审计： 对 API 请求进行安全审计，比如检查用户是否进行了敏感操作。
5. 事件触发： 根据 API 请求的结果，触发一些事件。 例如，当用户成功创建一个新文章时，你可以发送一封邮件通知管理员。

四、实战演练：代码示例

说了这么多，不如来点实际的。 让我们看几个 rest_post_dispatch 的代码示例。

示例 1：记录 API 请求日志

add_filter( 'rest_post_dispatch', 'my_log_api_request', 10, 3 );

function my_log_api_request( $result, $server, $request ) {
  $url = $request->get_route();
  $method = $request->get_method();
  $params = $request->get_params();
  $response_code = $result->get_status();

  $log_message = sprintf(
    "API Request: %s %snParams: %snResponse Code: %dn",
    $method,
    $url,
    json_encode( $params ),
    $response_code
  );

  error_log( $log_message );  // 将日志写入 error_log

  return $result;
}

这段代码会记录每个 API 请求的 URL、方法、参数和响应代码到 WordPress 的错误日志中。

示例 2：添加自定义头部

add_filter( 'rest_post_dispatch', 'my_add_custom_header', 10, 3 );

function my_add_custom_header( $result, $server, $request ) {
  $result->header( 'X-Custom-Header', 'Hello from rest_post_dispatch!' );
  return $result;
}

这段代码会在每个 API 响应中添加一个名为 X-Custom-Header 的自定义头部，值为 "Hello from rest_post_dispatch!"。

示例 3：修改响应数据

add_filter( 'rest_post_dispatch', 'my_modify_post_response', 10, 3 );

function my_modify_post_response( $result, $server, $request ) {
  // 只针对 /wp/v2/posts 接口进行修改
  if ( strpos( $request->get_route(), '/wp/v2/posts' ) !== false && $result instanceof WP_REST_Response ) {
    $data = $result->get_data();

    // 检查是否是单个文章的请求
    if ( isset( $data['id'] ) ) {
      $data['custom_field'] = 'This is a custom field!';
    } else {
      // 如果是文章列表，遍历每个文章并添加 custom_field
      foreach ( $data as &$post ) {
        $post['custom_field'] = 'This is a custom field!';
      }
    }

    $result->set_data( $data );
  }

  return $result;
}

这段代码会修改 /wp/v2/posts 接口的响应数据，给每个文章添加一个名为 custom_field 的字段，值为 "This is a custom field!"。

示例 4: 针对特定路由修改响应状态码

add_filter( 'rest_post_dispatch', 'my_change_status_code', 10, 3 );

function my_change_status_code( $result, $server, $request ) {
    // 只针对 /my-custom-route 路由进行修改
    if ( $request->get_route() === '/my-custom-route' && $result instanceof WP_REST_Response ) {
        $result->set_status( 201 ); // 将状态码修改为 201 Created
    }

    return $result;
}

// 注册一个自定义路由
add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/my-custom-route', array(
        'methods'  => 'GET',
        'callback' => 'my_custom_route_callback',
    ) );
} );

function my_custom_route_callback( WP_REST_Request $request ) {
    return new WP_REST_Response( array( 'message' => 'Hello from my custom route!' ), 200 );
}

这个例子展示了如何针对特定的路由 /my-custom-route，将默认的 200 状态码修改为 201 (Created)。这在创建新资源后非常有用。

五、注意事项

在使用 rest_post_dispatch 钩子时，需要注意以下几点：

1. 优先级： add_filter() 函数的第三个参数是优先级。 确保你的函数在其他函数之前或之后执行，以达到预期的效果。
2. 参数： 确保你的函数接收了正确的参数 ($result, $server, $request)，并且正确地处理这些参数。
3. 返回值： 你的函数 必须 返回 $result。 否则，API 响应可能会出错。
4. 性能： 避免在 rest_post_dispatch 钩子上执行耗时的操作， 否则会影响 API 的性能。如果需要执行耗时的操作，考虑使用异步任务或者队列。
5. 错误处理： 在你的函数中进行适当的错误处理，避免出现未捕获的异常。

六、高级用法：条件判断和路由匹配

有时候，你可能只想对特定的 API 接口应用 rest_post_dispatch 钩子。 这时，你可以使用 $request 对象来判断当前的 API 接口。

add_filter( 'rest_post_dispatch', 'my_conditional_logic', 10, 3 );

function my_conditional_logic( $result, $server, $request ) {
  $route = $request->get_route();

  // 只针对 /wp/v2/posts 接口进行处理
  if ( strpos( $route, '/wp/v2/posts' ) !== false ) {
    // ... 你的代码 ...
  }

  // 只针对 POST 请求进行处理
  if ( $request->get_method() === 'POST' ) {
    // ... 你的代码 ...
  }

  // 根据请求参数进行处理
  $category = $request->get_param( 'category' );
  if ( ! empty( $category ) ) {
    // ... 你的代码 ...
  }

  return $result;
}

在这个例子中，我们使用了 strpos() 函数来判断 URL 是否包含 /wp/v2/posts， 使用 get_method() 函数来判断请求方法是否为 POST， 使用 get_param() 函数来获取请求参数。

七、总结

rest_post_dispatch 钩子是 WordPress REST API 中一个非常强大的工具。 它可以让你在 API 响应返回给客户端之前，对响应数据进行修改、记录日志、添加自定义头部等等。 掌握了这个钩子，你就可以更好地控制 WordPress REST API 的行为， 满足各种各样的需求。

希望今天的讲座能帮助大家更深入地理解 rest_post_dispatch 钩子。 记住，实践是检验真理的唯一标准。 多写代码，多尝试，你就能掌握这个强大的工具。

今天的讲座就到这里，谢谢大家！ 祝大家编程愉快！