剖析 WordPress `rest_post_dispatch` 钩子源码：在 REST API 路由处理后执行自定义逻辑。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

嘿，大家好！今天咱们来聊聊WordPress REST API里一个相当给力的钩子——rest_post_dispatch。这玩意儿就像是REST API路由处理结束后的“善后处理小组”，能让你在API响应发送之前，对数据动动手脚，或者干点别的有用的事情。准备好了吗？咱们开始咯！

第一幕：钩子的诞生——rest_post_dispatch 是什么？

要理解rest_post_dispatch，首先要明白WordPress REST API的基本流程。简单来说，就是：

请求来了： 用户通过API端点发起请求（比如 /wp-json/wp/v2/posts/123）。
路由匹配： WordPress找到对应的路由处理函数（通常是一个回调函数，比如 get_post）。
处理请求： 路由处理函数负责获取数据，进行权限验证等操作。
生成响应： 路由处理函数返回一个 WP_REST_Response 对象，这个对象包含了API响应的数据、状态码、头部信息等。
发送响应： WordPress将 WP_REST_Response 对象转换为JSON格式，并通过HTTP发送给客户端。

而rest_post_dispatch钩子，就插在第4步和第5步之间。也就是说，在你辛辛苦苦写的路由处理函数返回了 WP_REST_Response 之后，但是在WordPress真正把响应发送出去之前，rest_post_dispatch 会被触发。你可以通过这个钩子，对 WP_REST_Response 对象进行修改，或者执行一些其他的操作。

第二幕：源码探秘——rest_post_dispatch 在哪里？

rest_post_dispatch 钩子的定义和触发点在 wp-includes/rest-api.php 文件中。具体来说，你可以在 rest_do_request 函数里找到它的身影。这个函数是REST API请求处理的核心。

function rest_do_request( $request ) {
    // 一些处理...

    $result = $route['callback'][0]->dispatch( $request );

    // 触发 rest_post_dispatch 钩子
    $result = apply_filters( 'rest_post_dispatch', rest_ensure_response( $result ), $server, $request );

    // 一些处理...

    return $result;
}

看到了吗？ apply_filters( 'rest_post_dispatch', ... ) 这行代码就是触发钩子的地方。它接收三个参数：

rest_post_dispatch: 钩子的名称。
rest_ensure_response( $result ): 路由处理函数返回的结果，会被强制转换为 WP_REST_Response 对象。
$server: WP_REST_Server 对象，包含了REST API服务器的配置信息。
$request: WP_REST_Request 对象，包含了客户端发起的请求信息。

第三幕：用法详解——如何使用 rest_post_dispatch？

现在，咱们来看看如何使用 rest_post_dispatch 钩子。最常见的用法就是修改API的响应数据。

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

function my_custom_rest_post_dispatch( $response, $server, $request ) {
    // 检查请求的路由，只对特定路由进行处理
    if ( $request->get_route() == '/wp/v2/posts' ) {
        // 获取响应数据
        $data = $response->get_data();

        // 遍历所有文章，添加一个自定义字段
        foreach ( $data as &$post ) {
            $post['my_custom_field'] = 'Hello, world!';
        }

        // 更新响应数据
        $response->set_data( $data );
    }

    return $response;
}

这段代码做了什么呢？

注册钩子： add_filter( 'rest_post_dispatch', 'my_custom_rest_post_dispatch', 10, 3 ) 告诉WordPress，当 rest_post_dispatch 钩子被触发时，执行 my_custom_rest_post_dispatch 函数。10 是优先级，3 是参数数量。
检查路由： if ( $request->get_route() == '/wp/v2/posts' ) 确保只对 /wp/v2/posts 这个路由的响应进行处理。这很重要，因为rest_post_dispatch是全局的，会对所有的REST API请求生效。
获取数据： $data = $response->get_data() 获取 WP_REST_Response 对象中的数据，通常是一个数组，包含了文章列表的信息。
修改数据： foreach ( $data as &$post ) { ... } 遍历所有文章，给每篇文章添加一个 my_custom_field 字段。
更新数据： $response->set_data( $data ) 将修改后的数据设置回 WP_REST_Response 对象。
返回响应： return $response 返回修改后的 WP_REST_Response 对象。

这样，当你访问 /wp-json/wp/v2/posts 这个API端点时，返回的JSON数据里，每篇文章都会多出一个 my_custom_field 字段。

第四幕：进阶用法——更多姿势解锁

rest_post_dispatch 的用法远不止修改数据这么简单。它还可以用来：

添加头部信息：

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

function my_custom_rest_add_header( $response, $server, $request ) {
    $response->header( 'X-Custom-Header', 'My Custom Value' );
    return $response;
}

这段代码会在API响应中添加一个名为 X-Custom-Header 的头部信息。

修改状态码：

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

function my_custom_rest_change_status( $response, $server, $request ) {
    if ( $request->get_route() == '/wp/v2/posts/123' ) {
        $response->set_status( 202 ); // Accepted
    }
    return $response;
}

这段代码会将 /wp/v2/posts/123 这个API端点的状态码修改为 202 Accepted。

记录日志：

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

function my_custom_rest_log_request( $response, $server, $request ) {
    error_log( 'REST API Request: ' . $request->get_route() );
    return $response;
}

这段代码会将每个REST API请求的路由记录到服务器的错误日志中。

第五幕：注意事项——避坑指南

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

性能问题： rest_post_dispatch 是一个全局钩子，会对所有的REST API请求生效。如果你的处理逻辑比较复杂，可能会影响API的性能。所以，一定要尽量优化你的代码，避免不必要的计算。
路由判断： 建议在钩子函数中判断请求的路由，只对特定的路由进行处理。这样可以避免对不相关的API请求造成影响。
优先级： add_filter 函数的第三个参数是优先级。优先级越小，钩子函数越先执行。你需要根据你的具体需求，选择合适的优先级。
返回值： 钩子函数必须返回 WP_REST_Response 对象。如果你忘记返回，或者返回了错误的数据类型，可能会导致API出错。
错误处理： 确保你的钩子函数能够处理各种可能的错误情况，比如数据不存在、权限不足等。

第六幕：实战演练——一个完整的例子

假设我们需要对 /wp/v2/posts 这个API端点返回的文章列表进行排序，按照文章的发布日期倒序排列。

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

function my_custom_rest_sort_posts( $response, $server, $request ) {
    if ( $request->get_route() == '/wp/v2/posts' ) {
        $data = $response->get_data();

        // 使用 usort 函数对文章列表进行排序
        usort( $data, function( $a, $b ) {
            return strtotime( $b['date'] ) - strtotime( $a['date'] );
        } );

        $response->set_data( $data );
    }

    return $response;
}

这段代码使用了 usort 函数，这是一个PHP内置的排序函数。它接收两个参数：

$data: 要排序的数组，也就是文章列表。
function( $a, $b ) { ... }: 一个比较函数，用于比较两个数组元素的大小。

比较函数返回一个整数：

如果 $a 应该排在 $b 之前，返回一个负数。
如果 $a 和 $b 相等，返回 0。
如果 $a 应该排在 $b 之后，返回一个正数。

在这个例子中，我们使用了 strtotime 函数将文章的发布日期转换为时间戳，然后比较两个时间戳的大小。这样就可以按照文章的发布日期倒序排列文章列表了。

第七幕：总结——rest_post_dispatch 的力量

rest_post_dispatch 钩子是一个非常强大的工具，可以让你在REST API响应发送之前，对数据进行各种各样的处理。无论是修改数据、添加头部信息，还是记录日志，rest_post_dispatch 都能帮你轻松实现。但是，在使用rest_post_dispatch 时，一定要注意性能问题和错误处理，避免对API造成不必要的影响。

第八幕：彩蛋——其他相关的钩子

除了 rest_post_dispatch 之外，WordPress REST API还有很多其他的钩子，可以让你在不同的阶段对API进行定制。比如：

钩子名称	触发时机	作用
`rest_pre_dispatch`	在REST API路由处理函数执行之前	允许在路由处理函数执行之前进行一些预处理，比如权限验证、数据准备等。
`rest_request_before_callbacks`	在REST API路由匹配之后，但是在执行回调函数之前。	允许在执行回调函数之前，修改请求参数、检查权限等。
`rest_authentication_errors`	在REST API认证过程中发生错误时。	可以用来定制认证错误信息，或者添加自定义的认证逻辑。
`rest_prepare_{$post_type}`	在REST API返回特定文章类型的文章数据之前。 `{$post_type}` 需要替换成实际的文章类型名称，比如 `rest_prepare_post`。	可以用来修改特定文章类型的文章数据，比如添加自定义字段、格式化数据等。
`rest_{$this->post_type}_query`	在REST API查询特定文章类型的文章数据之前。 `{$this->post_type}` 需要替换成实际的文章类型名称，比如 `rest_post_query`。	可以用来修改文章查询参数，比如添加自定义的查询条件、修改排序方式等。

掌握这些钩子，你就可以对WordPress REST API进行全方位的定制，打造出符合你需求的API接口。

好了，今天的讲座就到这里。希望大家对rest_post_dispatch 钩子有了更深入的了解。记住，灵活运用这些钩子，可以让你在WordPress开发中事半功倍！下次再见！

发表回复 取消回复

发表回复取消回复