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

大家好，欢迎来到今天的“WordPress 钩子大冒险”特别节目！今天我们要聊的是一个非常关键，但又经常被开发者忽略的钩子：rest_pre_dispatch。别看名字长，其实它就像一个“交通警察”，在WordPress REST API 路由真正开始“飙车”之前，给你一次掌控全局的机会。

准备好了吗？让我们一起深入了解这个钩子，看看它到底能做什么，以及如何利用它来构建更强大、更灵活的 WordPress 应用。

第一幕：rest_pre_dispatch 是个啥？

想象一下，你在一个拥挤的城市里开车，准备去参加一个重要的会议。这时，交通警察出现了，他可以根据当前的交通状况，临时改变你的路线，或者直接告诉你：“哥们儿，前面堵死了，换条路吧！”

rest_pre_dispatch 钩子在 WordPress REST API 的世界里，就扮演着类似交通警察的角色。它在REST API 请求被分发到对应的处理函数之前被触发。换句话说，它让你有机会：

检查请求是否合法： 比如，检查用户是否有权限访问某个资源。
修改请求参数： 比如，根据用户的角色，调整请求的参数。
直接返回结果： 比如，如果用户没有登录，直接返回一个错误信息，阻止后续的处理。
完全接管请求： 比如，用你自己的逻辑来处理请求，完全忽略 WordPress 默认的处理方式。

第二幕：rest_pre_dispatch 的工作原理

rest_pre_dispatch 钩子是一个 filter 钩子，这意味着它接收一个参数，并返回一个值。它的基本形式如下：

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

function your_custom_function( $result, $server, $request ) {
  // 你的逻辑
  return $result;
}

让我们来分解一下：

add_filter( 'rest_pre_dispatch', 'your_custom_function', 10, 3 );：这行代码告诉 WordPress，当 rest_pre_dispatch 钩子被触发时，执行 your_custom_function 函数。
- 'rest_pre_dispatch'：钩子的名称。
- 'your_custom_function'：你自定义的函数名称。
- 10：优先级，数字越小，优先级越高，越早执行。
- 3：传递给函数的参数个数。
function your_custom_function( $result, $server, $request ) { ... }：这是你自定义的函数，它接收三个参数：
- $result：这是 WordPress 默认的处理结果。如果之前有其他函数处理过这个钩子，那么 $result 可能已经被修改过了。如果 $result 不是 null，那么 WordPress 会直接返回 $result，而不会执行后续的路由处理。这就是我们“完全接管请求”的关键。
- $server：这是一个 WP_REST_Server 类的实例，包含了 REST API 服务器的信息。你可以通过它访问服务器的配置、路由信息等等。
- $request：这是一个 WP_REST_Request 类的实例，包含了请求的所有信息，包括 URL、方法、参数、头部信息等等。这是我们分析请求，做出决策的关键。

返回值：$result 的重要性

$result 的返回值决定了 WordPress 如何处理 REST API 请求。不同的返回值有不同的含义：

返回值	含义
`null`	告诉 WordPress 继续执行默认的 REST API 路由处理。也就是说，你的函数只是“观察”了一下请求，并没有做出任何改变。
任何非 `null` 值	告诉 WordPress 停止执行默认的 REST API 路由处理，并直接返回你提供的值。这个值可以是任何东西：一个 `WP_REST_Response` 对象（包含数据、状态码、头部信息），一个错误对象，甚至是一个简单的字符串。重要的是，WordPress 会将这个值作为最终的响应返回给客户端。这就是我们“完全接管请求”的方式。
`WP_Error` 对象	告诉 WordPress 请求处理过程中发生了错误。 WordPress 会将这个错误对象转换为一个包含错误信息的 JSON 响应，并返回给客户端。这是一种标准的错误处理方式。

第三幕：实战演练：几个 rest_pre_dispatch 的应用场景

好了，理论讲了一堆，现在让我们来看几个实际的例子，看看 rest_pre_dispatch 到底能做什么。

场景一：权限验证

假设你有一个自定义的 REST API 接口，只有登录用户才能访问。你可以使用 rest_pre_dispatch 来检查用户是否已经登录，如果没有登录，就返回一个错误信息。

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

function check_user_login( $result, $server, $request ) {
  // 获取当前用户
  $user = wp_get_current_user();

  // 如果用户没有登录
  if ( 0 === $user->ID ) {
    // 创建一个错误对象
    $error = new WP_Error(
      'rest_not_logged_in',
      __( '你必须登录才能访问这个接口。', 'my-plugin' ),
      array( 'status' => 401 )
    );

    // 返回错误对象，阻止后续处理
    return $error;
  }

  // 用户已经登录，继续执行
  return $result;
}

在这个例子中：

我们首先获取当前用户的信息。
然后，我们检查用户的 ID 是否为 0。如果是 0，说明用户没有登录。
如果用户没有登录，我们创建一个 WP_Error 对象，包含错误代码、错误信息和状态码。
最后，我们返回这个 WP_Error 对象。 WordPress 会将这个对象转换为一个 JSON 响应，并返回给客户端。

场景二：参数修改

假设你有一个 REST API 接口，可以根据用户的角色，返回不同的数据。你可以使用 rest_pre_dispatch 来修改请求的参数，以便后续的处理函数可以根据用户的角色来返回不同的数据。

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

function modify_request_params( $result, $server, $request ) {
  // 获取当前用户
  $user = wp_get_current_user();

  // 如果用户是管理员
  if ( in_array( 'administrator', $user->roles ) ) {
    // 修改请求参数，添加一个 'show_all' 参数
    $request->set_param( 'show_all', true );
  }

  // 继续执行
  return $result;
}

在这个例子中：

我们首先获取当前用户的信息。
然后，我们检查用户是否是管理员。
如果是管理员，我们使用 $request->set_param() 方法，添加一个名为 show_all 的参数，并将其设置为 true。
后续的处理函数就可以根据 show_all 参数的值，来决定是否返回所有的数据。

场景三：完全接管请求

有时候，你可能需要完全接管 REST API 请求的处理，用你自己的逻辑来处理请求，完全忽略 WordPress 默认的处理方式。 rest_pre_dispatch 也可以做到这一点。

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

function handle_custom_request( $result, $server, $request ) {
  // 获取请求的路径
  $route = $request->get_route();

  // 如果请求的路径是 '/my-custom-route'
  if ( '/my-custom-route' === $route ) {
    // 创建一个自定义的响应
    $response = new WP_REST_Response( array(
      'message' => '这是我的自定义响应！',
    ) );

    // 设置响应的状态码
    $response->set_status( 200 );

    // 返回响应，阻止后续处理
    return $response;
  }

  // 继续执行
  return $result;
}

在这个例子中：

我们首先获取请求的路径。
然后，我们检查请求的路径是否是 /my-custom-route。
如果是，我们创建一个自定义的 WP_REST_Response 对象，包含一个简单的消息。
我们设置响应的状态码为 200。
最后，我们返回这个 WP_REST_Response 对象。 WordPress 会将这个对象转换为一个 JSON 响应，并返回给客户端。

第四幕：rest_pre_dispatch 的高级用法

rest_pre_dispatch 还有一些高级用法，可以让你更好地控制 REST API 请求的处理。

使用 $server 对象： $server 对象包含了 REST API 服务器的信息，你可以通过它访问服务器的配置、路由信息等等。例如，你可以使用 $server->get_routes() 方法，获取所有已注册的路由信息。
处理不同的请求方法： 你可以使用 $request->get_method() 方法，获取请求的方法（GET, POST, PUT, DELETE 等等），然后根据不同的方法，执行不同的逻辑。
处理不同的请求参数： 你可以使用 $request->get_params() 方法，获取所有请求参数，然后根据不同的参数，执行不同的逻辑。

表格总结：rest_pre_dispatch 的优缺点

优点	缺点
提供了在路由处理之前拦截和修改 REST API 请求的能力。	如果使用不当，可能会导致 REST API 请求的处理逻辑变得复杂和难以理解。
可以用于实现各种自定义的逻辑，例如权限验证、参数修改、请求重定向等等。	可能会影响 REST API 的性能，因为每个请求都需要经过 `rest_pre_dispatch` 钩子的处理。
可以与其他 WordPress 钩子结合使用，实现更强大的功能。	如果与其他插件或主题的钩子发生冲突，可能会导致意想不到的问题。

第五幕：总结与建议

rest_pre_dispatch 钩子是一个非常强大的工具，可以让你在 WordPress REST API 的世界里拥有更多的控制权。但是，它也需要谨慎使用，因为它可能会导致代码变得复杂和难以维护。

以下是一些使用 rest_pre_dispatch 钩子的建议：

只在你真正需要的时候才使用它。 如果你的需求可以用其他方式实现，例如使用标准的 WordPress 权限系统，那么就不要使用 rest_pre_dispatch 钩子。
保持你的代码简洁和易于理解。 尽量将你的逻辑分解成小的、独立的函数，并添加详细的注释。
测试你的代码。 确保你的代码能够正常工作，并且不会影响 REST API 的性能。

总而言之，rest_pre_dispatch 钩子就像一把双刃剑，用得好，可以让你事半功倍，用不好，可能会让你陷入困境。所以，在使用它之前，一定要充分了解它的工作原理，并仔细考虑你的需求。

好了，今天的“WordPress 钩子大冒险”就到这里了。希望大家通过今天的学习，能够更好地理解 rest_pre_dispatch 钩子，并将其应用到你的 WordPress 项目中。

感谢大家的收看，我们下次再见！

发表回复 取消回复

发表回复取消回复