深入理解 WordPress `rest_api_init` 钩子源码：在 REST API 初始化时添加功能的最佳实践。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

大家好，我是老码农，今天咱们来聊聊 WordPress REST API 的一个重要钩子：rest_api_init。这玩意儿就像是 REST API 这辆豪华跑车的发动机启动仪式，你可以在这里定制它的各种小部件，让它更符合你的需求。

一、REST API 的前世今生：简单回顾

在深入 rest_api_init 之前，咱们先简单回顾下 WordPress REST API。想象一下，以前我们想从 WordPress 拿数据，通常得用 WP_Query、get_posts() 啥的，然后在主题或者插件里捣鼓半天。这就像是自己造轮子，费时费力。

REST API 出现后，就方便多了。它提供了一套标准的接口，用 HTTP 请求（GET、POST、PUT、DELETE）就能访问 WordPress 的数据，就像是直接从数据库里取数据一样，简洁高效。这就像是有了高速公路，数据传输嗖嗖的。

二、rest_api_init：发动机启动仪式

rest_api_init 是一个 action 钩子，它会在 WordPress REST API 初始化的时候被触发。换句话说，在 REST API 准备好接受请求之前，你会得到一个机会，可以对它进行配置和扩展。这就像是赛车手在比赛前检查车辆，确保一切就绪。

三、rest_api_init 的使用场景：发挥你的想象力

rest_api_init 的应用场景非常广泛，只要你想在 REST API 初始化时做点什么，它就能派上用场。比如：

注册自定义路由： 这是最常见的用法。你可以创建自己的 API 端点，提供特定的数据或功能。比如，创建一个获取“今日最佳文章”的接口。
修改现有路由： 如果你对 WordPress 默认的 API 端点不满意，可以通过 rest_api_init 修改它们的行为。比如，给文章的 API 响应添加一些自定义字段。
添加中间件： 在 API 请求处理过程中添加一些自定义逻辑，比如权限验证、数据转换等。
注册自定义数据类型： 如果你想通过 REST API 管理自定义文章类型或者自定义字段，需要在 rest_api_init 中注册它们。

四、代码示例：手把手教你玩转 rest_api_init

光说不练假把式，咱们来看几个实际的代码示例。

1. 注册自定义路由：获取“今日最佳文章”

<?php
/**
 * Plugin Name: Custom REST API Route
 */

add_action( 'rest_api_init', 'register_today_best_posts_route' );

function register_today_best_posts_route() {
    register_rest_route(
        'myplugin/v1', // 命名空间
        '/today-best-posts', // 路由
        array(
            'methods'  => 'GET', // 请求方法
            'callback' => 'get_today_best_posts', // 回调函数
            'permission_callback' => '__return_true', // 允许所有用户访问
        )
    );
}

function get_today_best_posts( WP_REST_Request $request ) {
    $args = array(
        'date_query' => array(
            array(
                'year'  => date( 'Y' ),
                'month' => date( 'm' ),
                'day'   => date( 'd' ),
            ),
        ),
        'posts_per_page' => 5, // 获取前5篇
        'orderby'   => 'comment_count', //按评论数排序
        'order'     => 'DESC', //降序
    );

    $posts = get_posts( $args );

    if ( empty( $posts ) ) {
        return new WP_Error( 'no_posts', 'No posts found for today.', array( 'status' => 404 ) );
    }

    $data = array();
    foreach ( $posts as $post ) {
        $data[] = array(
            'id'    => $post->ID,
            'title' => $post->post_title,
            'link'  => get_permalink( $post ),
        );
    }

    return rest_ensure_response( $data );
}

这段代码做了什么？

add_action( 'rest_api_init', 'register_today_best_posts_route' )：告诉 WordPress，在 REST API 初始化的时候，执行 register_today_best_posts_route 函数。
register_rest_route()：注册一个自定义路由。
- 'myplugin/v1'：命名空间，用于区分不同的 API 路由。建议使用插件或主题的名称作为命名空间。
- '/today-best-posts'：路由路径。通过 https://yourdomain.com/wp-json/myplugin/v1/today-best-posts 访问。
- 'methods' => 'GET'：指定请求方法为 GET。
- 'callback' => 'get_today_best_posts'：指定回调函数为 get_today_best_posts。当请求这个路由时，会执行这个函数。
- 'permission_callback' => '__return_true'：允许所有用户访问。如果需要权限验证，可以自定义一个函数来验证用户权限。
get_today_best_posts()：获取“今日最佳文章”的回调函数。
- 使用 WP_Query 获取当天的文章，并按评论数排序。
- 将文章信息格式化成数组，并返回。
- rest_ensure_response()：确保返回的数据是 WP_REST_Response 对象，这是 REST API 的标准响应格式。
WP_Error: 如果没有文章，返回一个 WP_Error 对象，并设置状态码为 404。

2. 修改现有路由：给文章 API 响应添加自定义字段

<?php
/**
 * Plugin Name: Custom REST API Field
 */

add_action( 'rest_api_init', 'add_custom_post_field' );

function add_custom_post_field() {
    register_rest_field(
        'post', // 文章类型
        'my_custom_field', // 字段名称
        array(
            'get_callback'    => 'get_post_custom_field', // 获取字段值的回调函数
            'update_callback' => null, // 更新字段值的回调函数，如果只读，可以设置为 null
            'schema'          => array( // 字段的 Schema，用于描述字段的类型和属性
                'type'        => 'string',
                'description' => 'Custom field for posts',
                'context'     => array( 'view', 'edit' ), // 允许在哪些上下文中显示该字段
            ),
        )
    );
}

function get_post_custom_field( $object, $field_name, $request ) {
    // 获取文章的自定义字段值
    $custom_field_value = get_post_meta( $object['id'], 'my_custom_field', true );
    return $custom_field_value ? $custom_field_value : 'Default Value';
}

这段代码做了什么？

register_rest_field()：注册一个自定义字段。
- 'post'：文章类型。你可以指定其他文章类型，比如 'page' 或自定义文章类型。
- 'my_custom_field'：字段名称。这个名称会在 API 响应中作为字段的键名。
- 'get_callback' => 'get_post_custom_field'：获取字段值的回调函数。当请求文章 API 时，会执行这个函数来获取字段的值。
- 'update_callback' => null：更新字段值的回调函数。如果你希望这个字段是只读的，可以设置为 null。
- 'schema'：字段的 Schema，用于描述字段的类型和属性。这有助于 API 客户端了解字段的结构和用途。
get_post_custom_field()：获取自定义字段值的回调函数。
- 使用 get_post_meta() 获取文章的自定义字段值。
- 如果自定义字段存在，则返回其值，否则返回默认值。

现在，当你请求文章 API 时，你会看到响应中多了一个 my_custom_field 字段，它的值就是文章的自定义字段 my_custom_field 的值。

3. 添加中间件：权限验证

假设你想对某个 API 端点进行权限验证，只有登录用户才能访问。你可以这样做：

<?php
/**
 * Plugin Name: Custom REST API Middleware
 */

add_action( 'rest_api_init', 'add_authentication_middleware' );

function add_authentication_middleware() {
    register_rest_route(
        'myplugin/v1',
        '/protected-route',
        array(
            'methods'  => 'GET',
            'callback' => 'get_protected_data',
            'permission_callback' => 'check_authentication', // 权限验证回调函数
        )
    );
}

function check_authentication() {
    if ( ! is_user_logged_in() ) {
        return new WP_Error( 'rest_not_logged_in', 'You are not currently logged in.', array( 'status' => 401 ) );
    }
    return true;
}

function get_protected_data( WP_REST_Request $request ) {
    return array( 'message' => 'This is protected data for logged-in users.' );
}

这段代码的关键在于 permission_callback 参数，它指定了一个名为 check_authentication 的函数作为权限验证的回调函数。

check_authentication()：检查用户是否已登录。
- 如果用户未登录，则返回一个 WP_Error 对象，并设置状态码为 401（Unauthorized）。
- 如果用户已登录，则返回 true，表示允许访问。

五、rest_api_init 的最佳实践：避免踩坑

在使用 rest_api_init 时，有一些最佳实践可以帮助你避免踩坑：

使用命名空间： 所有的自定义路由都应该使用命名空间，以避免与其他插件或主题的路由冲突。
注册 Schema： 为你的自定义字段注册 Schema，这有助于 API 客户端了解字段的结构和用途。
权限验证： 对需要权限保护的 API 端点进行权限验证，确保只有授权用户才能访问。
数据验证和清理： 对 API 请求中的数据进行验证和清理，防止恶意数据破坏系统。
错误处理： 在回调函数中进行错误处理，并返回合适的 HTTP 状态码和错误信息。
性能优化： 避免在 rest_api_init 中执行耗时的操作，这会影响 API 的响应速度。
文档： 为你的自定义 API 端点编写文档，方便其他开发者使用。

六、总结：rest_api_init 是你的好帮手

rest_api_init 是 WordPress REST API 的一个强大的钩子，它允许你在 API 初始化时添加自定义功能。通过它可以注册自定义路由、修改现有路由、添加中间件等，从而扩展 REST API 的功能。掌握 rest_api_init，你就可以更好地利用 REST API 来构建各种应用。

一些关键点总结成表格：

概念/参数	描述	示例
`rest_api_init`	Action 钩子，在 REST API 初始化时触发。	`add_action( 'rest_api_init', 'my_custom_function' );`
`register_rest_route()`	用于注册自定义 REST API 路由的函数。	`register_rest_route( 'myplugin/v1', '/my-route', ... );`
命名空间	用于区分不同插件或主题的 API 路由，避免冲突。	`'myplugin/v1'`
路由路径	API 端点的 URL 路径。	`'/my-route'`
`methods`	指定允许的 HTTP 请求方法 (GET, POST, PUT, DELETE)。	`'GET'`, `'POST'`
`callback`	当请求路由时执行的回调函数，用于处理请求并返回数据。	`'my_callback_function'`
`permission_callback`	用于验证用户是否有权限访问该路由的回调函数。返回 `true` 表示允许访问，返回 `WP_Error` 表示拒绝访问。	`'is_user_logged_in'`, `'my_permission_check'`
`register_rest_field()`	用于注册自定义字段到现有的 REST API 响应中。	`register_rest_field( 'post', 'my_field', ... );`
`schema`	用于描述自定义字段的类型和属性，帮助 API 客户端了解字段的结构和用途。	`'type' => 'string'`, `'description' => 'My custom field'`
`WP_Error`	用于在 API 请求中返回错误信息。	`new WP_Error( 'error_code', 'Error message', array( 'status' => 400 ) )`

希望今天的讲座对大家有所帮助。记住，熟能生巧，多动手实践，才能真正掌握 rest_api_init 的精髓。祝大家编程愉快！

发表回复 取消回复

发表回复取消回复