WP REST API：内部和自定义

在本系列的前一部分中，我们了解了如何通过WP REST API远程创建，更新和删除内容。它使我们能够创建与平台无关的应用程序，这些应用程序可与WordPress驱动的后端无缝协作，从而为用户提供丰富的体验。

在本系列的当前部分中，我们将研究WP REST API的内部结构以及它们如何共同为API提供动力。之后，我们将学习修改默认端点的服务器响应以包括自定义字段。

具体来说，在当前文章中，我们将：

了解WP REST API的内部类和方法
修改默认端点的服务器响应
了解如何使自定义字段可编辑

因此，让我们开始看看WP REST API的内部。

WP REST API的内部类和方法

WP REST API中的类可以分为以下两类：

基础结构类 ：这些是负责将API组合在一起的基本类。他们不执行任何数据转换。
端点类 ：这些类负责对资源（如帖子，页面，用户，评论等）执行CRUD操作。

让我们看一下以上两个类别中的每个类别。

基础设施类

一起为REST API提供支持的三个基础结构类如下：

WP_REST_Server
WP_REST_Request
WP_REST_Response

WP_REST_Server

这是WP REST API的核心类，该类通过注册路由，提供请求和准备响应来实现REST服务器。它格式化要传递给客户端的数据，如果发生错误，它会通过包含错误代码和消息正文来准备错误。它还检查身份验证。

我们已经在/wp-json索引端点上进行了大量工作，以检查站点的所有功能和支持的路由。负责检索站点索引的方法get_index()也位于此类中。

对于服务请求和准备响应， WP_REST_Server类使用WP_REST_Request和WP_REST_Response分别班。

WP_REST_Request

WP_REST_Request类实现WP REST API的请求对象。它包含来自请求的数据，例如标头和请求正文，并由WP_REST_Server类传递给回调函数。它还检查沿请求传递的参数是否有效，并在必要时执行数据清理。

WP_REST_Response

顾名思义， WP_REST_Response类实现了响应对象。它包含必要的数据，例如响应状态代码和响应正文。

现在让我们看一下端点类。

端点类

WP REST API中的终结点类负责执行CRUD操作。这些类包括WP_REST_Posts_Controller ， WP_REST_Taxonomies_Controller ， WP_REST_Users_Controller等。所有这些端点类都扩展了单个抽象类WP_REST_Controller ，该抽象类提供了用于修改数据的一致模式。

WP_REST_Controller类包括用于执行CRUD操作的方法，例如get_item() ， create_item() ， update_item() ， delete_item()等方法。这些方法必须由子类重写，方法是实现它们自己的抽象以检索，创建，更新和修改数据。

您可以在官方文档中找到有关这些类及其内部方法的更多信息。

了解了WP REST API的内部类之后，让我们看一下如何修改默认端点的服务器响应以包括自定义字段。

修改服务器响应

在上一节中，我们研究了构建API的内部类和方法。这些类和方法一起驱动了整个API，并为开发人员提供了一种扩展API的方法，以解决不同的情况和用例。

WP REST API以可预测的方式公开数据。这包括各种资源，例如帖子，帖子元，页面和用户，以及它们的标准属性。但是，这些数据并不总是符合每个WordPress网站或用户的需求。因此，WP REST API提供了一种修改服务器为每个默认路由返回的数据的方法。

register_rest_field()方法提供了一种在对象的响应中添加或更新字段的方法。但是，API从不鼓励从响应更改字段，因为它可能会为希望从服务器获得标准响应的客户端带来兼容性问题。因此，如果需要更改字段，则应考虑将字段复制为所需的值。

同样，强烈建议不要删除默认字段，原因是客户端可能希望使用它。如果您需要服务器返回的响应的较小子集，则除了默认上下文（例如view或edit之外，还应该创建其他上下文。

但是，我们可以将一个字段安全地添加到服务器为一个或多个对象返回的响应中。这些字段可以包含从post或user meta到任何其他任意值的任何值。

在下一节中，我们将使用register_rest_field()方法将自定义字段添加到服务器为post对象返回的响应中。

使用`register_rest_field()`方法

如前所述， register_rest_field()方法可用于在服务器返回的响应中添加或更新字段。此方法接受三个参数：

$object_type
$attribute
$args

$object_type参数可以是字符串，也可以是包含要为其添加字段的所有对象的名称的数组。这些对象可以是post ， term ， comment ， user等。如果需要将自定义字段添加到自定义帖子类型，则$object_type参数将是帖子类型的名称。

$attribute参数是自定义字段的名称。此名称将作为键及其值显示在服务器响应中。

$args数组是一个关联数组，可以包含以下三个键：

$get_callback
$update_callback
$schema

前两个键的值是用于获取或更新自定义字段的值的方法的名称。最后一个$schema键定义用于定义自定义字段的架构的方法或变量。

以上所有键都是可选的，但是如果不添加它们，则不会添加功能。例如，如果您定义$get_callback键，但$get_callback $update_callback键，则将添加检索功能，但不会添加更新功能。如果省略$get_callback键，则该字段将根本不会添加到响应中。

register_rest_field()方法通过修改$wp_rest_additional_fields变量来工作。此数组变量按对象类型保存注册的字段，服务器将在响应中返回该字段。每当通过register_rest_field()方法register_rest_field()字段时，该字段就会添加到$wp_rest_additional_fields变量中。但是，强烈建议不要手动修改$wp_rest_additional_fields变量。

将自定义字段添加到响应

熟悉了register_rest_field()方法之后，我们现在可以修改post对象的响应。这里的典型用例是添加作者显示名称字段，当在索引页面上列出帖子时通常需要此字段。由于标准响应不包含此字段，因此我们可以使用register_rest_field()方法将其包含在响应中。

我们首先创建一个简单的插件。因此，在/ wp-content / plugins目录中创建一个名为rest-response-modifier的新文件夹。创建一个空的index.php文件并粘贴以下插件定义：

<?php
/**
 * Plugin Name: REST Response Modifier
 * Description: A very simple plugin for development and testing purpose to modify the response of the REST API plugin.
 * Author: Bilal Shahid
 * Author URI: http://imbilal.com
 */

register_rest_field()方法应在rest_api_init操作中注册。因此，我们创建了一个名为bs_add_custom_rest_fields()的函数，并将bs_add_custom_rest_fields()绑定到rest_api_init钩子：

<?php
add_action( 'rest_api_init', 'bs_add_custom_rest_fields' );

function bs_add_custom_rest_fields() {

}

请注意，这里不需要打开PHP标签<?php ，但是我已经包含了它们，因此语法可以正确突出显示。

在bs_add_custom_rest_fields()函数内部，我们可以使用register_rest_field()方法包括作者姓名字段：

function bs_add_custom_rest_fields() {
    // schema for the bs_author_name field
    $bs_author_name_schema = array(
        'description'   => 'Name of the post author',
        'type'          => 'string',
        'context'       =>   array( 'view' )
    );

    // registering the bs_author_name field
    register_rest_field(
        'post',
        'bs_author_name',
        array(
            'get_callback'      => 'bs_get_author_name',
            'update_callback'   => null,
            'schema'            => $bs_author_name_schema
        )
    );
}

如上一节所述， register_rest_field()方法中的第一个参数是我们要为其修改响应的对象的名称。由于我们需要修改post对象的响应，因此我们传递与第一个参数相同的参数。

上面代码中的第二个参数是将出现在响应中的字段名称。在响应中添加自定义字段的名称始终是一个好习惯，以确保最大的前向兼容性，并且以后不会被其他插件覆盖。因此，我们在第二个参数中传递bs_author_name作为自定义字段的$attribute 。

上面代码中的第三个也是最后一个参数是回调方法和模式的数组。该数组在$get_callback和$update_callback键中分别包含用于检索和更新自定义字段的回调方法的名称。我们传递bs_get_author_name函数作为检索回调方法。我们将在短期内定义此功能。

对于$update_callback键，我们传递null因为这是一个只读字段，并且我们不需要更新帖子的作者姓名。

对于$schema键，我们传递一个名为$bs_author_name_schema的数组。该数组为该字段保留了各种属性，例如数据类型，上下文和描述。

现在我们唯一需要定义的就是bs_get_author_name()函数，它将用作自定义字段的$get_callback方法。下面是此函数的代码：

/**
 * Callback for retrieving author name
 * @param  array            $object         The current post object
 * @param  string           $field_name     The name of the field
 * @param  WP_REST_request  $request        The current request
 * @return string                           The name of the author
 */
function bs_get_author_name( $object, $field_name, $request ) {
    return get_the_author_meta( 'display_name', $object['author'] );
}

$get_callback方法接收以下三个参数：

$object ：当前对象。就我们而言，这是当前职位。
$field_name ：要添加的自定义字段的名称。
1. $request ：请求对象。

我们正在使用$object参数的$author属性，该属性包含帖子作者的ID。通过使用get_the_author_meta()函数，我们检索并返回当前帖子作者的显示名称。

现在已经注册了该字段，我们可以将GET请求发送到/wp/v2/posts路由以查看其是否正常运行：

这是邮递员的回复：

当我们向/wp/v2/posts路由发送OPTIONS请求时，此新注册的自定义字段也会连同其模式一起出现在服务器响应中：

因此，作者姓名属性的自定义字段已成功注册。但是此字段是只读的，因为我们无法通过发送POST请求来对其进行更新。在下一节中，我们将注册一个可编辑字段，以用于查看浏览量。

注册可编辑字段

现在，我们将为帖子查看次数注册一个自定义字段。我们将仅使用WP REST API处理字段的实际注册，而忽略了增加计数数量的实现。

以下是bs_post_views自定义字段注册及其模式的代码：

// schema for bs_post_views field
$bs_post_views_schema = array(
    'description'   => 'Post views count',
    'type'          => 'integer',
    'context'       =>   array( 'view', 'edit' )
);

// registering the bs_post_views field
register_rest_field(
    'post',
    'bs_post_views',
    array(
        'get_callback'      => 'bs_get_post_views',
        'update_callback'   => 'bs_update_post_views',
        'schema'            => $bs_post_views_schema
    )
);

该代码与上一节中编写的代码相似，不同之处在于，该代码现在包括用于$update_callback键的回调方法bs_update_post_views 。此功能负责更新字段的值。

$bs_post_views_schema模式数组中的$context属性包括用于view和edit两个值。 $context参数中包含编辑值可确保bs_post_views字段在更新后在服务器响应中返回。

检索和更新回调方法如下：

/**
* Callback for retrieving post views count
* @param  array             $object         The current post object
* @param  string            $field_name     The name of the field
* @param  WP_REST_request   $request        The current request
* @return integer                           Post views count
*/
function bs_get_post_views( $object, $field_name, $request ) {
    return (int) get_post_meta( $object['id'], $field_name, true );
}

/**
* Callback for updating post views count
* @param  mixed     $value          Post views count
* @param  object    $object         The object from the response
* @param  string    $field_name     Name of the current field
* @return bool|int
*/
function bs_update_post_views( $value, $object, $field_name ) {
    if ( ! $value || ! is_numeric( $value ) ) {
        return;
    }

    return update_post_meta( $object->ID, $field_name, (int) $value );
}

该代码非常简单，因为它使用get_post_meta()和update_post_meta()方法分别检索和更新值。

bs_get_post_views()方法首先获取bs_post_views元键的元值，并将其转换为整数，然后再返回。

$update_callback传递的回调方法接收以下三个参数：

$value ：字段的新值。
$object ：响应中的当前对象。
$field_name ：要更新的字段的名称。

在bs_update_post_views()方法中，我们首先检查所传递的值是否不为空且为数字值。如果没有，我们什么也不做就返回。

如果该值为数字，则将其传递给update_post_meta()函数，该函数在将其类型转换为有效整数后将其保存到数据库中。

成功注册该字段后，让我们通过发送GET请求对其进行测试：

$ GET /wp/v2/posts

以下是上述请求的示例响应：

如上图所示，给定帖子的bs_post_views字段的当前值为0。这是因为get_post_meta()方法返回一个空字符串，因为它找不到bs_post_views元键的元值，并且在PHP中将一个空字符串类型转换为整数会导致0。

我们可以通过向/wp/v2/posts/<id>端点发送POST请求来更新bs_post_views字段。请求的JSON主体如下：

{
    "bs_post_views": 4050
}

如果请求成功，服务器将返回200-OK状态代码以及更新的post对象，该对象还包括bs_post_views字段：

bs_post_views定制字段现已更新。

请注意，我们在请求中发送了JSON正文以更新字段。 JSON正文包含字段名称bs_post_views其整数值为4050 。如果尝试发送非数字值，例如“abc1234” ，则该字段将不会更新，因为我们在bs_update_post_views()回调方法中有条件检查数字值。

以下是该插件的完整源代码：

<?php
/**
 * Plugin Name: REST Response Modifier
 * Description: A very simple plugin for development and testing purpose to modify the response of the REST API plugin.
 * Author: Bilal Shahid
 * Author URI: http://imbilal.com
 */

add_action( 'rest_api_init', 'bs_add_custom_rest_fields' );

/**
 * Function for registering custom fields
 */
function bs_add_custom_rest_fields() {
    // schema for the bs_author_name field
    $bs_author_name_schema = array(
        'description'   => 'Name of the post author',
        'type'          => 'string',
        'context'       =>   array( 'view' )
    );

    // registering the bs_author_name field
    register_rest_field(
        'post',
        'bs_author_name',
        array(
            'get_callback'      => 'bs_get_author_name',
            'update_callback'   => null,
            'schema'            => $bs_author_name_schema
        )
    );

    // schema for bs_post_views field
    $bs_post_views_schema = array(
        'description'   => 'Post views count',
        'type'          => 'integer',
        'context'       =>   array( 'view', 'edit' )
    );

    // registering the bs_post_views field
    register_rest_field(
        'post',
        'bs_post_views',
        array(
            'get_callback'      => 'bs_get_post_views',
            'update_callback'   => 'bs_update_post_views',
            'schema'            => $bs_post_views_schema
        )
    );
}

/**
 * Callback for retrieving author name
 * @param  array            $object         The current post object
 * @param  string           $field_name     The name of the field
 * @param  WP_REST_request  $request        The current request
 * @return string                           The name of the author
 */
function bs_get_author_name( $object, $field_name, $request ) {
    return get_the_author_meta( 'display_name', $object['author'] );
}

/**
 * Callback for retrieving post views count
 * @param  array            $object         The current post object
 * @param  string           $field_name     The name of the field
 * @param  WP_REST_request  $request        The current request
 * @return integer                          Post views count
 */
function bs_get_post_views( $object, $field_name, $request ) {
    return (int) get_post_meta( $object['id'], $field_name, true );
}
/**
 * Callback for updating post views count
 * @param  mixed    $value          Post views count
 * @param  object   $object         The object from the response
 * @param  string   $field_name     Name of the current field
 * @return bool|int
 */
function bs_update_post_views( $value, $object, $field_name ) {
    if ( ! $value || ! is_numeric( $value ) ) {
        return;
    }

    return update_post_meta( $object->ID, $field_name, (int) $value );
}

这些都是为了修改默认API端点的服务器响应。我们几乎没有涉及修改REST API的内容，因为它提供了比仅修改服务器响应更大的灵活性。这包括通过自定义控制器和名称空间添加对自定义内容类型的支持，以及注册用于公开和修改数据的自定义路由。我们将在以后的文章中尝试介绍这些高级主题。