探究 WordPress `WP_REST_Response` 类的源码：如何构建 REST API 的响应对象。

WordPress REST API 响应构建大师班：解剖 WP_REST_Response

各位靓仔靓女，大家好！我是你们今天的WordPress REST API响应构建主讲人，人称“代码界的段子手”。 今天咱们不讲枯燥的理论，而是要深入到WordPress的腹地，扒开 WP_REST_Response 类的源码，看看它到底是如何把数据包装成一个让浏览器和客户端都喜笑颜开的REST API响应的。

准备好了吗？ 让我们开始这场刺激的源码探险之旅吧！

1. 什么是 WP_REST_Response？

首先，我们要搞清楚WP_REST_Response 到底是什么。 简单来说，它就是WordPress REST API用来构建响应对象的基石。 你可以把它想象成一个快递盒子，用来装你要返回给客户端的数据，以及一些关于这个数据的额外信息，比如状态码、HTTP头部等等。

在REST API的世界里，响应不仅仅是数据本身，还包括很多元数据。 WP_REST_Response 类的作用就是把这些东西整合起来，按照RESTful的规范打包好，然后发送给客户端。

2. WP_REST_Response 类的骨架：属性和方法

我们先来看看 WP_REST_Response 类的基本结构，也就是它的属性和方法。

属性名	类型	描述
$data	mixed	响应的主体数据，可以是任何类型。
$status	int	HTTP状态码，例如200 OK, 404 Not Found。
$headers	array	HTTP头部，例如Content-Type, Cache-Control。
$matched_route	string	匹配到的REST API路由。
$matched_handler	array	处理该路由的回调函数。

再来看看一些常用的方法：

方法名	作用
__construct( $data = null, $status = 200, $headers = array() )	构造函数，用于初始化响应对象。
get_data()	获取响应数据。
set_data( $data )	设置响应数据。
get_status()	获取HTTP状态码。
set_status( $status )	设置HTTP状态码。
get_headers()	获取HTTP头部。
header( $key, $value )	设置单个HTTP头部。
set_headers( $headers )	设置多个HTTP头部。
link_header( $rel, $link )	添加 Link 头部，用于实现 HATEOAS。
is_error()	检查响应是否包含错误信息（通过 WP_Error 对象）。
as_json()	将响应数据转换为JSON格式。
as_xml()	将响应数据转换为XML格式（需要额外扩展）。

这些属性和方法就像是组成一个快递盒子的各个部件，我们需要合理地使用它们，才能构建出一个完美的REST API响应。

3. 构造 WP_REST_Response 对象

创建一个 WP_REST_Response 对象非常简单，只需要使用 new 关键字即可。

$response = new WP_REST_Response();

当然，你也可以在构造函数中直接传入数据、状态码和头部信息：

$data = array(
    'message' => 'Hello, REST API!',
    'status'  => 'success'
);
$status = 200;
$headers = array(
    'Content-Type' => 'application/json',
);

$response = new WP_REST_Response( $data, $status, $headers );

这样，一个包含数据的，状态码为200，并且指定了Content-Type为application/json的响应对象就创建好了。

4. 设置响应数据：set_data()

set_data() 方法用于设置响应对象中的数据。 它可以接受任何类型的数据，包括数组、对象、字符串等等。

$response = new WP_REST_Response();
$data = array(
    'name' => '张三',
    'age'  => 30,
);
$response->set_data( $data );

// 或者，直接设置字符串
$response->set_data( 'Hello, world!' );

灵活使用 set_data() 方法，可以让你轻松地构建各种类型的响应数据。

5. 设置 HTTP 状态码：set_status()

HTTP 状态码是REST API响应中非常重要的一个组成部分。 它告诉客户端请求的处理结果，例如成功、失败、重定向等等。

set_status() 方法用于设置HTTP状态码。 你需要传入一个整数作为参数，表示状态码的值。

$response = new WP_REST_Response();

// 设置状态码为 200 OK
$response->set_status( 200 );

// 设置状态码为 404 Not Found
$response->set_status( 404 );

// 设置状态码为 500 Internal Server Error
$response->set_status( 500 );

常用的HTTP状态码及其含义如下表所示：

状态码	含义
200	OK，请求成功。
201	Created，资源创建成功。
204	No Content，请求成功，但没有返回任何内容。
400	Bad Request，客户端请求错误。
401	Unauthorized，未授权，需要进行身份验证。
403	Forbidden，禁止访问，没有权限。
404	Not Found，资源未找到。
500	Internal Server Error，服务器内部错误。
503	Service Unavailable，服务不可用。

选择合适的HTTP状态码，可以清晰地表达请求的处理结果，帮助客户端更好地理解API的行为。

6. 设置 HTTP 头部：header() 和 set_headers()

HTTP 头部提供了关于响应的额外信息，例如Content-Type、Cache-Control等等。

header() 方法用于设置单个HTTP头部。 你需要传入两个参数：头部的名称和值。

$response = new WP_REST_Response();

// 设置 Content-Type 头部
$response->header( 'Content-Type', 'application/json' );

// 设置 Cache-Control 头部
$response->header( 'Cache-Control', 'max-age=3600' );

set_headers() 方法用于设置多个HTTP头部。 你需要传入一个关联数组作为参数，数组的键表示头部的名称，值表示头部的值。

$response = new WP_REST_Response();

$headers = array(
    'Content-Type'  => 'application/json',
    'Cache-Control' => 'max-age=3600',
    'X-Custom-Header' => 'Hello, world!',
);

$response->set_headers( $headers );

常用的HTTP头部及其含义如下表所示：

头部名称	含义
Content-Type	响应内容的类型，例如application/json, text/html。
Cache-Control	缓存控制，例如max-age=3600表示缓存3600秒。
ETag	资源的唯一标识符，用于缓存验证。
Last-Modified	资源的最后修改时间，用于缓存验证。
Location	重定向的目标URL。

合理设置HTTP头部，可以优化API的性能、安全性，并提供更好的用户体验。

7. HATEOAS：link_header()

HATEOAS (Hypermedia as the Engine of Application State) 是一种REST API设计风格，它通过在响应中包含链接，让客户端能够发现和使用API的功能。

link_header() 方法用于添加Link头部，实现HATEOAS。 你需要传入两个参数：链接的关系 (rel) 和链接的URL。

$response = new WP_REST_Response();

// 添加一个链接，指向用户的个人资料页面
$response->link_header( 'profile', 'https://example.com/users/123' );

// 添加一个链接，指向用户的博客文章列表
$response->link_header( 'posts', 'https://example.com/users/123/posts' );

添加Link头部后，客户端可以通过解析头部信息，找到相关的API资源，从而实现更灵活的API交互。

8. 处理错误：WP_Error 和 is_error()

在REST API开发中，错误处理是一个非常重要的环节。 当发生错误时，我们需要向客户端返回错误信息，而不是让程序崩溃或者返回不明确的结果。

WordPress提供了 WP_Error 类来表示错误信息。 你可以使用 WP_Error 对象来封装错误代码、错误信息和额外的数据。

if ( ! user_can( $user_id, 'edit_posts' ) ) {
    $error = new WP_Error(
        'rest_cannot_edit',
        __( 'Sorry, you are not allowed to edit posts.' ),
        array( 'status' => 403 )
    );
    return $error;
}

WP_REST_Response 类会自动检测响应数据是否为 WP_Error 对象。 如果是，它会将HTTP状态码设置为400 (Bad Request)，并将错误信息转换为JSON格式返回给客户端。

is_error() 方法用于检查响应对象是否包含错误信息。

$response = your_api_function();

if ( is_wp_error( $response ) ) {
    // 处理错误
    $error_code = $response->get_error_code();
    $error_message = $response->get_error_message();
    // ...
} else {
    // 处理成功响应
    $data = $response->get_data();
    // ...
}

通过使用 WP_Error 和 is_error() 方法，你可以有效地处理API中的错误，并向客户端提供清晰的错误信息。

9. 转换为 JSON：as_json()

REST API 最常用的数据格式是 JSON。 WP_REST_Response 类提供了 as_json() 方法，可以将响应数据转换为 JSON 格式的字符串。

$response = new WP_REST_Response(
    array( 'message' => 'Hello, world!' ),
    200,
    array( 'Content-Type' => 'application/json' )
);

$json_string = $response->as_json();

// 输出 JSON 字符串
echo $json_string; // {"message":"Hello, world!"}

实际上，在 WordPress REST API 中，当你返回一个 WP_REST_Response 对象时，WordPress 会自动调用 as_json() 方法，将响应转换为 JSON 格式，并设置 Content-Type 头部为 application/json。 所以，你通常不需要手动调用 as_json() 方法。

10. 实战演练：构建一个简单的 API 接口

现在，让我们通过一个简单的例子，来演示如何使用 WP_REST_Response 类构建一个API接口。

/**
 * 注册一个 REST API 路由
 */
add_action( 'rest_api_init', function () {
    register_rest_route( 'my-plugin/v1', '/message', array(
        'methods'  => 'GET',
        'callback' => 'my_plugin_get_message',
    ) );
} );

/**
 * 处理 API 请求的回调函数
 *
 * @return WP_REST_Response
 */
function my_plugin_get_message() {
    $data = array(
        'message' => 'Hello, from my WordPress REST API!',
        'time'    => current_time( 'mysql' ),
    );

    $response = new WP_REST_Response( $data, 200 );

    // 添加一个自定义的 HTTP 头部
    $response->header( 'X-Custom-Header', 'This is a custom header value' );

    return $response;
}

在这个例子中，我们注册了一个名为 my-plugin/v1/message 的REST API路由。 当客户端发送GET请求到这个路由时，my_plugin_get_message() 函数会被调用。

my_plugin_get_message() 函数创建了一个包含消息和时间的数组，然后使用 WP_REST_Response 类将数据、状态码和自定义头部封装成一个响应对象，并返回给客户端。

客户端发送请求后，会收到如下JSON响应：

{
    "message": "Hello, from my WordPress REST API!",
    "time": "2023-10-27 10:00:00"
}

同时，客户端还会收到一个名为 X-Custom-Header 的自定义HTTP头部。

11. 扩展 WP_REST_Response 类

如果你觉得 WP_REST_Response 类提供的功能不够用，你可以扩展它，添加自己的方法和属性。

例如，你可以添加一个 as_xml() 方法，将响应数据转换为 XML 格式。

class My_REST_Response extends WP_REST_Response {
    /**
     * 将响应数据转换为 XML 格式
     *
     * @return string
     */
    public function as_xml() {
        // 这里实现 XML 转换的逻辑
        $data = $this->get_data();
        $xml = '<root>';
        foreach ( $data as $key => $value ) {
            $xml .= '<' . $key . '>' . $value . '</' . $key . '>';
        }
        $xml .= '</root>';
        return $xml;
    }
}

然后，你可以在你的API接口中使用 My_REST_Response 类：

function my_plugin_get_message() {
    $data = array(
        'message' => 'Hello, from my WordPress REST API!',
        'time'    => current_time( 'mysql' ),
    );

    $response = new My_REST_Response( $data, 200 );
    $response->header( 'Content-Type', 'application/xml' );

    return $response;
}

客户端将会收到XML格式的响应。

12. 总结

WP_REST_Response 类是WordPress REST API中构建响应对象的关键。 通过理解它的属性和方法，你可以灵活地控制响应数据、HTTP状态码、HTTP头部，并实现HATEOAS和错误处理。

希望今天的课程能够帮助你更好地理解 WP_REST_Response 类，并在你的WordPress REST API开发中大显身手！

记住，代码的世界没有绝对的对错，只有不断地学习和实践，才能成为真正的编程大师。 祝大家编程愉快！ 咱们下期再见！