分析 WordPress `rest_pre_dispatch` 钩子源码：如何在 REST API 路由处理前执行自定义逻辑，如缓存。

大家好，我是老码，今天咱们聊聊WordPress REST API里的一个“妙人儿”—— rest_pre_dispatch 钩子。这个钩子可厉害了，能在REST API路由处理之前“截胡”，让咱们有机会插入一些自定义逻辑，比如缓存。想象一下，你开了一家餐厅，rest_pre_dispatch就像站在门口的迎宾，可以先看看顾客是不是熟客，如果是，直接带到预留的包间，省去了排队点菜的麻烦。

什么是rest_pre_dispatch？

首先，我们要搞清楚rest_pre_dispatch是个什么玩意儿。简单来说，它是一个filter钩子，存在于WordPress REST API处理请求的核心流程中。当一个REST API请求进来时，WordPress会根据请求的URL和HTTP方法，找到对应的路由处理函数。但在真正执行这个处理函数之前，rest_pre_dispatch钩子会被触发。

这个钩子允许你返回一个WP_REST_Response对象，或者一个WP_Error对象，从而完全跳过原有的路由处理函数。如果你什么都不返回（返回null），那么WordPress会继续执行原定的路由处理函数。这就是“截胡”的含义：你可以选择自己处理请求，也可以选择放行让WordPress继续。

rest_pre_dispatch的源码解读

想要玩转rest_pre_dispatch，咱们得先看看它藏在WordPress源码的哪个角落里。这个钩子位于 wp-includes/rest-api.php 文件中。具体来说，它是在 WP_REST_Server::dispatch() 方法中被调用的。

以下是简化后的相关代码片段（WordPress版本可能略有差异，但核心逻辑不变）：

// wp-includes/rest-api.php

/**
 * Dispatch a REST request.
 *
 * @since 4.4.0
 *
 * @param WP_REST_Request|null $request Request to dispatch.
 * @return WP_REST_Response|WP_Error Result of the dispatch.
 */
public function dispatch( $request = null ) {
    if ( empty( $request ) ) {
        $request = $this->request;
    }

    // Find the route and handler.
    $result = $this->match_request();

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

    list( $route, $handler ) = $result;

    /**
     * Filters the REST API pre-dispatch check.
     *
     * Allows bypassing the handling of the request entirely. The filter
     * receives the request object and returns either a WP_REST_Response to short-circuit
     * the request, a WP_Error to indicate an error, or null to fall through
     * to the default dispatching.
     *
     * @since 4.4.0
     *
     * @param WP_REST_Response|WP_Error|null $result  Result of the dispatch, usually null.
     * @param WP_REST_Server                $this    Server instance.
     * @param WP_REST_Request               $request Request to dispatch.
     */
    $result = apply_filters( 'rest_pre_dispatch', null, $this, $request );

    if ( ! is_null( $result ) ) {
        return $result;
    }

    // ... 后续的路由处理逻辑 ...
}

从代码中可以看出，apply_filters( 'rest_pre_dispatch', null, $this, $request ); 这行就是rest_pre_dispatch钩子的调用点。它接收三个参数：

• null: 初始值，表示默认情况下不进行任何操作，让WordPress继续处理请求。
• $this: WP_REST_Server 实例，可以访问服务器的各种属性和方法。
• $request: WP_REST_Request 实例，包含了请求的所有信息，比如URL、HTTP方法、请求参数等等。

rest_pre_dispatch 的应用场景：缓存

现在，我们来聊聊rest_pre_dispatch的一个重要应用场景：缓存。想象一下，你的网站有一个REST API接口，用来获取热门文章列表。这个接口的请求量很大，每次都查询数据库会给服务器带来不小的压力。这时候，就可以使用rest_pre_dispatch来实现缓存，把热门文章列表缓存起来，下次请求直接返回缓存数据，避免重复查询数据库。

实现步骤：

1. 注册钩子： 在你的插件或者主题的 functions.php 文件中，使用 add_filter() 函数注册 rest_pre_dispatch 钩子。
2. 检查缓存： 在钩子函数中，根据请求的URL和参数，生成一个唯一的缓存键，然后检查缓存中是否存在该键对应的数据。
3. 返回缓存或继续处理： 如果缓存命中，则创建一个 WP_REST_Response 对象，包含缓存数据，并返回。如果缓存未命中，则返回 null，让WordPress继续执行原有的路由处理函数。
4. 更新缓存： 如果请求最终由WordPress处理，并在处理函数中成功获取了数据，则将数据存入缓存，以便下次使用。

代码示例：

下面是一个简单的示例，演示如何使用rest_pre_dispatch来实现REST API接口的缓存：

<?php
/**
 * Plugin Name: REST API Cache Example
 * Description: Demonstrates how to use rest_pre_dispatch to cache REST API responses.
 */

add_filter( 'rest_pre_dispatch', 'rest_api_cache_filter', 10, 3 );

/**
 * Filters the REST API pre-dispatch check for caching.
 *
 * @param WP_REST_Response|WP_Error|null $result  Result of the dispatch, usually null.
 * @param WP_REST_Server                $server  Server instance.
 * @param WP_REST_Request               $request Request to dispatch.
 *
 * @return WP_REST_Response|WP_Error|null
 */
function rest_api_cache_filter( $result, $server, $request ) {
    // 只缓存特定路由，例如 /wp/v2/posts
    if ( strpos( $request->get_route(), '/wp/v2/posts' ) === false ) {
        return $result; // 不是我们要缓存的路由，直接放行
    }

    // 生成缓存键
    $cache_key = 'rest_api_' . md5( $request->get_route() . serialize( $request->get_params() ) );

    // 尝试从缓存中获取数据
    $cached_data = get_transient( $cache_key );

    if ( $cached_data ) {
        // 缓存命中，返回缓存数据
        $response = new WP_REST_Response( $cached_data );
        $response->header( 'X-Cache', 'HIT' ); // 添加一个自定义头部，表示缓存命中
        return $response;
    } else {
        // 缓存未命中，返回 null，让 WordPress 继续处理请求
        return null;
    }
}

add_action( 'rest_after_dispatch', 'rest_api_cache_update', 10, 3 );

/**
 * Action to update the cache after a REST API request is dispatched.
 *
 * @param WP_REST_Response $response The REST response.
 * @param WP_REST_Server   $server   The REST server instance.
 * @param WP_REST_Request  $request  The REST request.
 */
function rest_api_cache_update( $response, $server, $request ) {
    // 只有当请求成功并且是我们要缓存的路由时才更新缓存
    if ( $response->is_error() || strpos( $request->get_route(), '/wp/v2/posts' ) === false ) {
        return;
    }

    // 生成缓存键
    $cache_key = 'rest_api_' . md5( $request->get_route() . serialize( $request->get_params() ) );

    // 获取响应数据
    $data = $response->get_data();

    // 将数据存入缓存，设置过期时间为 1 小时
    set_transient( $cache_key, $data, 1 * HOUR_IN_SECONDS );
}

代码解释：

• rest_api_cache_filter() 函数：
  • 首先检查请求的路由是否是 /wp/v2/posts，如果不是，则直接返回 null，让WordPress继续处理请求。
  • 然后，根据请求的路由和参数，生成一个唯一的缓存键。
  • 接着，尝试从WordPress的瞬态（transient）缓存中获取数据。
  • 如果缓存命中，则创建一个 WP_REST_Response 对象，包含缓存数据，并设置一个自定义的HTTP头部 X-Cache: HIT，表示缓存命中。
  • 如果缓存未命中，则返回 null，让WordPress继续处理请求。
• rest_api_cache_update() 函数：
  • 在WordPress处理完请求后，如果请求成功，则获取响应数据，并将其存入缓存。
  • 缓存的过期时间设置为1小时。

注意事项：

• 缓存键的设计： 缓存键的设计非常重要，要确保能够唯一标识一个请求。一般来说，可以把请求的URL、HTTP方法、请求参数等等都包含在缓存键中。
• 缓存过期时间： 缓存过期时间的设置需要根据实际情况进行调整。如果数据更新频繁，则需要设置较短的过期时间。
• 缓存清理： 当数据发生变化时，需要及时清理缓存，以避免返回过期的数据。可以使用WordPress的 delete_transient() 函数来清理缓存。
• 错误处理： 在缓存过程中，需要进行错误处理，例如，如果缓存读取失败，则应该返回 null，让WordPress继续处理请求。
• 安全： 确保缓存的数据是安全的，避免缓存敏感信息。

rest_pre_dispatch 的其他应用场景

除了缓存之外，rest_pre_dispatch 还可以用于其他一些场景，例如：

• 权限验证： 在执行路由处理函数之前，检查用户是否具有访问该接口的权限。
• 请求参数验证： 在执行路由处理函数之前，验证请求参数是否合法。
• 日志记录： 记录REST API请求的详细信息，例如请求时间、请求IP、请求参数等等。
• 重定向： 根据某些条件，将请求重定向到其他接口。
• 修改请求： 在执行路由处理函数之前，修改请求的参数或头部信息。

rest_pre_dispatch 与 rest_authentication_errors 的区别

有些同学可能会把 rest_pre_dispatch 和 rest_authentication_errors 混淆。虽然它们都可以在REST API请求处理之前“截胡”，但它们的用途是不同的。

• rest_authentication_errors 主要用于处理身份验证错误。如果用户身份验证失败，则可以使用 rest_authentication_errors 返回一个 WP_Error 对象，阻止请求继续执行。
• rest_pre_dispatch 的用途更加广泛，可以用于任何需要在路由处理函数之前执行的逻辑，例如缓存、权限验证、请求参数验证等等。

简单总结一下：

钩子名称	主要用途	返回值类型	适用场景
rest_pre_dispatch	在路由处理前执行自定义逻辑，可跳过路由处理	WP_REST_Response、WP_Error、null	缓存、权限验证、参数验证、日志记录、重定向、修改请求
rest_authentication_errors	处理身份验证错误，阻止请求继续执行	WP_Error、null	用户身份验证失败，例如用户名密码错误、Token过期等。

总结

rest_pre_dispatch 是一个非常强大的钩子，可以让你在WordPress REST API请求处理流程中插入自定义逻辑，实现各种各样的功能。 掌握好这个钩子，可以让你更好地控制REST API的行为，提高网站的性能和安全性。希望今天的讲解能够帮助大家更好地理解和使用rest_pre_dispatch。

记住，玩转WordPress，就是玩转各种钩子！ 祝大家编码愉快！