分析 WordPress `do_action(‘rest_api_init’)` 的源码：此钩子在何时被触发，以及其重要性。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位朋友，晚上好！很高兴今晚能跟大家聊聊 WordPress 里一个非常重要的钩子——do_action('rest_api_init')。别看它名字挺高大上，其实理解起来并不难。咱们今天就深入源码，扒一扒它的老底，看看它到底在啥时候被触发，又肩负着怎样的使命。

一、打个招呼：WordPress REST API，你好！

在正式开始之前，咱们先简单聊聊 WordPress REST API。简单来说，它就像一个翻译器，把 WordPress 的数据转换成 JSON 格式，这样其他的应用程序（比如手机 APP、单页面应用）就能轻松地和 WordPress 交流了。想象一下，你用手机 APP 发表了一篇文章，这个 APP 就是通过 REST API 把数据发送给 WordPress，然后 WordPress 才能把文章保存到数据库里。

所以，REST API 在 WordPress 的现代化发展中扮演着至关重要的角色。而 do_action('rest_api_init') 钩子，就是 REST API 初始化过程中的一个关键节点。

二、源码探秘：rest_api_init 的前世今生

为了彻底搞清楚 do_action('rest_api_init')，我们得深入 WordPress 的源码。找到 rest_api_init 这个钩子的定义和触发位置。

首先，打开 WordPress 的核心文件 wp-includes/rest-api.php (或者你使用的 WordPress 版本的对应文件，路径可能略有不同)。在这个文件中，你会找到类似这样的代码：

/**
 * Fires after the REST API is initialized.
 *
 * @since 4.4.0
 */
do_action( 'rest_api_init' );

这段代码清晰地表明，do_action('rest_api_init') 是在 REST API 初始化之后触发的。那么，问题来了：REST API 什么时候初始化呢？

继续往上翻代码，你会发现一个名为 rest_api_loaded() 的函数（或者类似的函数，具体函数名可能因版本而异）。这个函数负责初始化 REST API，其中就包括触发 do_action('rest_api_init') 钩子。

function rest_api_loaded() {
    // 各种 REST API 相关的初始化操作...

    /**
     * Fires after the REST API is initialized.
     *
     * @since 4.4.0
     */
    do_action( 'rest_api_init' );
}

现在，我们知道 do_action('rest_api_init') 是在 rest_api_loaded() 函数中触发的。接下来，我们需要找到 rest_api_loaded() 函数在什么地方被调用。

一般来说，rest_api_loaded() 函数会在 WordPress 加载过程的某个阶段被调用，通常是在 init 钩子之后。让我们在 wp-includes/plugin.php 文件中搜索一下，看看有没有什么线索。

add_action( 'init', 'rest_api_init' );

function rest_api_init() {
    // 初始化 REST API 的代码
    require_once ABSPATH . WPINC . '/rest-api.php';

    if ( did_action( 'rest_api_init' ) ) {
        return;
    }

    rest_api_loaded();
}

从上面的代码中，我们可以得出以下结论：

rest_api_init() 函数被挂载到 init 钩子上。
rest_api_init() 函数会包含 rest-api.php 文件，该文件包含了 rest_api_loaded() 函数的定义和 do_action('rest_api_init') 的触发。
do_action('rest_api_init') 钩子会在 init 钩子之后被触发。

三、重要性分析：rest_api_init 钩子的意义

那么，do_action('rest_api_init') 钩子到底有什么用呢？为什么 WordPress 要专门设置这么一个钩子？

简单来说，do_action('rest_api_init') 钩子为开发者提供了一个机会，可以在 REST API 初始化完成后，执行一些自定义的操作。常见的用途包括：

注册自定义的 REST API 路由： 这是最常见的用法。通过 register_rest_route() 函数，你可以注册自己的 API 接口，让外部应用程序可以访问你的数据或执行你的代码。
自定义 REST API 的认证方式： WordPress 默认的认证方式可能不符合你的需求，你可以通过这个钩子来修改认证方式，比如使用 JWT (JSON Web Token) 认证。
修改 REST API 的响应数据： 你可以通过这个钩子来修改 REST API 返回的数据格式，比如添加一些自定义字段，或者对数据进行一些处理。
添加自定义的 REST API 中间件： 类似于 Express.js 中的中间件，你可以在 REST API 请求处理过程中插入一些自定义的代码，比如进行权限验证、日志记录等等。

四、实战演练：注册自定义 REST API 路由

为了更好地理解 do_action('rest_api_init') 钩子的用法，我们来写一个简单的例子：注册一个自定义的 REST API 路由，返回一些简单的信息。

首先，在你的主题的 functions.php 文件中，或者在一个自定义的插件中，添加以下代码：

add_action( 'rest_api_init', 'my_register_rest_route' );

function my_register_rest_route() {
    register_rest_route(
        'myplugin/v1', // 命名空间
        '/info', // 路由
        array(
            'methods'  => 'GET', // 请求方法
            'callback' => 'my_get_info', // 回调函数
        )
    );
}

function my_get_info( WP_REST_Request $request ) {
    return array(
        'name'    => 'My Custom API',
        'version' => '1.0',
        'author'  => 'Your Name',
    );
}

这段代码做了以下几件事：

使用 add_action() 函数，将 my_register_rest_route() 函数挂载到 rest_api_init 钩子上。
my_register_rest_route() 函数使用 register_rest_route() 函数注册了一个新的 REST API 路由。
- 'myplugin/v1' 是命名空间，用于区分不同的 API 接口。建议使用插件或主题的名称作为命名空间，并加上版本号。
- '/info' 是路由，用于指定 API 接口的 URL。
- array(...) 是一个数组，用于配置 API 接口的各种参数。
  - 'methods' => 'GET' 指定 API 接口只接受 GET 请求。
  - 'callback' => 'my_get_info' 指定处理 API 请求的回调函数。
my_get_info() 函数是一个回调函数，用于处理 API 请求，并返回数据。
- WP_REST_Request $request 是一个对象，包含了请求的所有信息，比如请求参数、请求头等等。
- return array(...) 返回一个数组，这个数组会被转换成 JSON 格式，作为 API 接口的响应数据。

现在，你可以使用任何 HTTP 客户端（比如浏览器、Postman）来访问这个 API 接口：

http://your-wordpress-site.com/wp-json/myplugin/v1/info

你应该会看到类似这样的 JSON 响应：

{
    "name": "My Custom API",
    "version": "1.0",
    "author": "Your Name"
}

五、进阶技巧：自定义 REST API 认证

WordPress 默认的 REST API 认证方式是基于 Cookie 的，这意味着只有登录用户才能访问需要认证的 API 接口。如果你需要使用其他的认证方式，比如 JWT (JSON Web Token) 认证，你可以通过 do_action('rest_api_init') 钩子来实现。

以下是一个简单的例子，演示如何使用 JWT 认证：

注意： 这个例子只是一个演示，实际使用中需要进行更多的安全考虑。

首先，你需要安装一个 JWT 相关的插件，比如 "JWT Authentication for WP REST API"。

然后，在你的主题的 functions.php 文件中，或者在一个自定义的插件中，添加以下代码：

add_filter( 'rest_authentication_errors', 'my_rest_authentication_errors' );

function my_rest_authentication_errors( $errors ) {
    // 如果已经有错误，直接返回
    if ( ! empty( $errors ) ) {
        return $errors;
    }

    // 获取 Authorization 请求头
    $auth_header = $_SERVER['HTTP_AUTHORIZATION'] ?? '';

    // 如果没有 Authorization 请求头，返回错误
    if ( empty( $auth_header ) ) {
        return new WP_Error(
            'rest_authentication_required',
            'Authorization header is missing.',
            array( 'status' => 401 )
        );
    }

    // 从 Authorization 请求头中提取 JWT Token
    $token = str_replace( 'Bearer ', '', $auth_header );

    // 验证 JWT Token
    $user_id = my_validate_jwt_token( $token ); // 你需要自己实现这个函数

    // 如果 JWT Token 无效，返回错误
    if ( ! $user_id ) {
        return new WP_Error(
            'rest_authentication_invalid_jwt',
            'Invalid JWT token.',
            array( 'status' => 401 )
        );
    }

    // 设置当前用户
    wp_set_current_user( $user_id );

    return $errors;
}

// 你需要自己实现这个函数，用于验证 JWT Token
function my_validate_jwt_token( $token ) {
    // TODO: 验证 JWT Token 的逻辑
    // 比如，检查 Token 是否过期，签名是否正确等等

    // 如果 JWT Token 有效，返回用户 ID
    // 否则，返回 false

    // 示例代码（假设 JWT Token 中包含了 user_id）：
    // $decoded_token = JWT::decode( $token, SECRET_KEY, array( 'HS256' ) );
    // return $decoded_token->data->user->id;

    return false; // 默认返回 false
}

这段代码做了以下几件事：

使用 add_filter() 函数，将 my_rest_authentication_errors() 函数挂载到 rest_authentication_errors 过滤器上。
my_rest_authentication_errors() 函数负责验证 REST API 请求的认证信息。
- 首先，检查是否已经有错误。如果有，直接返回。
- 然后，获取 Authorization 请求头，如果不存在，返回一个错误。
- 从 Authorization 请求头中提取 JWT Token。
- 调用 my_validate_jwt_token() 函数验证 JWT Token。
- 如果 JWT Token 无效，返回一个错误。
- 如果 JWT Token 有效，设置当前用户。

六、注意事项：安全第一！

在使用 do_action('rest_api_init') 钩子时，一定要注意安全问题。特别是在注册自定义 REST API 路由时，要仔细验证用户的输入，防止 SQL 注入、XSS 攻击等安全漏洞。

以下是一些建议：

使用 sanitize_text_field() 函数对用户输入进行过滤。
使用 esc_sql() 函数对 SQL 查询进行转义。
使用 wp_kses() 函数对 HTML 代码进行过滤。
对 API 接口进行权限验证，确保只有授权用户才能访问。
定期更新 WordPress 和插件，及时修复安全漏洞。

七、总结：rest_api_init，你的好帮手

do_action('rest_api_init') 钩子是 WordPress REST API 初始化过程中的一个重要节点，它为开发者提供了一个机会，可以在 REST API 初始化完成后，执行一些自定义的操作。通过这个钩子，你可以注册自定义的 REST API 路由，自定义 REST API 的认证方式，修改 REST API 的响应数据，添加自定义的 REST API 中间件等等。

希望今天的分享能帮助大家更好地理解 do_action('rest_api_init') 钩子的作用和用法。记住，安全第一！在使用 REST API 时，一定要注意安全问题，确保你的 WordPress 网站的安全。

附录：常用函数和钩子

函数/钩子	描述
`do_action('rest_api_init')`	在 REST API 初始化完成后触发的钩子，用于注册自定义 REST API 路由、自定义认证方式等。
`register_rest_route()`	注册一个新的 REST API 路由。
`WP_REST_Request`	一个对象，包含了 REST API 请求的所有信息，比如请求参数、请求头等等。
`add_filter('rest_authentication_errors')`	用于过滤 REST API 认证错误信息的钩子，可以用于自定义 REST API 的认证方式。
`sanitize_text_field()`	对用户输入进行过滤，防止 XSS 攻击。
`esc_sql()`	对 SQL 查询进行转义，防止 SQL 注入。
`wp_kses()`	对 HTML 代码进行过滤，防止 XSS 攻击。

希望这份附录能帮助大家更好地理解 WordPress REST API 相关的函数和钩子。

今天的讲座就到这里，感谢大家的聆听！如果大家还有什么问题，欢迎随时提问。祝大家学习愉快！

发表回复 取消回复

发表回复取消回复