分析 WordPress `WP_REST_Request` 类的源码：它如何封装 HTTP 请求，并提供对参数的访问。

各位观众老爷，今天咱们就来聊聊 WordPress REST API 里一个相当重要的角色 —— WP_REST_Request。这家伙就像个勤劳的快递员，负责把 HTTP 请求里里外外的信息都打包好，送到你的插件或主题里，让你能轻松地拆包取用，从而构建各种神奇的功能。

开场白：HTTP 请求的变形金刚

想象一下，你通过浏览器发送了一个 HTTP 请求，就像扔了个包裹出去。这个包裹里包含了各种信息：请求方法（是 GET 还是 POST？）、URL、请求头、请求体（比如你提交的表单数据）等等。 WP_REST_Request 的作用，就是把这个包裹拆开，把里面的东西分门别类地放好，然后给你提供各种方便的接口，让你想拿什么就拿什么，想怎么用就怎么用。 它就像一个 HTTP 请求的变形金刚，能变成各种你需要的形式。

源码剖析：WP_REST_Request 的结构

WP_REST_Request 类定义在 wp-includes/rest-api/class-wp-rest-request.php 文件里。 它主要负责封装以下信息：

• 请求方法 (Method): GET, POST, PUT, DELETE 等等。
• URL: 请求的 URL。
• 请求头 (Headers): Content-Type, Authorization 等等。
• 参数 (Parameters): 通过 URL query string 或请求体传递的参数。
• 属性 (Attributes): 一些附加的属性，比如认证信息。

下面我们来扒一扒它的源码，看看它到底是怎么工作的。

<?php

/**
 * Class WP_REST_Request
 */
class WP_REST_Request {

    /**
     * Request method.
     *
     * @var string
     */
    protected $method;

    /**
     * Request route.
     *
     * @var string
     */
    protected $route;

    /**
     * Request headers.
     *
     * @var array
     */
    protected $headers = array();

    /**
     * Request parameters.
     *
     * @var array
     */
    protected $params = array();

    /**
     * Attributes for the request.
     *
     * @var array
     */
    protected $attributes = array();

    /**
     * Constructor.
     *
     * @param string $method  Optional. Request method. Default 'GET'.
     * @param string $route Optional. The REST route being dispatched.
     */
    public function __construct( $method = 'GET', $route = null ) {
        $this->set_method( $method );
        if ( $route ) {
            $this->set_route( $route );
        }
    }

    /**
     * Sets the HTTP method for the request.
     *
     * @param string $method HTTP method.
     */
    public function set_method( $method ) {
        $this->method = strtoupper( $method );
    }

    /**
     * Retrieves the HTTP method for the request.
     *
     * @return string HTTP method.
     */
    public function get_method() {
        return $this->method;
    }

    // ... 其他方法，后面会逐步讲解 ...
}

重点属性一览

属性名	类型	描述
$method	string	HTTP 请求方法 (GET, POST, PUT, DELETE, 等等)。
$route	string	REST API 路由，例如 /wp/v2/posts。
$headers	array	HTTP 请求头，键值对形式 (例如 ['Content-Type' => 'application/json'])。
$params	array	请求参数，包括 URL 查询字符串参数和请求体参数。
$attributes	array	其他属性，用于存储一些额外的信息，比如认证状态。

构造函数：初始化请求对象

__construct() 方法用于创建 WP_REST_Request 对象。 你可以指定请求方法和路由，如果没有指定，默认是 GET 方法。

public function __construct( $method = 'GET', $route = null ) {
    $this->set_method( $method );
    if ( $route ) {
        $this->set_route( $route );
    }
}

设置和获取请求方法：set_method() 和 get_method()

这两个方法用于设置和获取 HTTP 请求方法。 set_method() 会将方法名转换为大写，确保统一格式。

public function set_method( $method ) {
    $this->method = strtoupper( $method );
}

public function get_method() {
    return $this->method;
}

设置和获取路由：set_route() 和 get_route()

这两个方法用于设置和获取 REST API 路由。路由定义了请求的目标资源。

public function set_route( $route ) {
    $this->route = $route;
}

public function get_route() {
    return $this->route;
}

管理请求头：get_headers(), set_headers(), get_header(), set_header()

WP_REST_Request 提供了多个方法来管理请求头：

• get_headers(): 获取所有请求头。
• set_headers(): 设置所有请求头，会覆盖已有的请求头。
• get_header(): 获取指定名称的请求头的值。
• set_header(): 设置指定名称的请求头的值。

public function get_headers() {
    return $this->headers;
}

public function set_headers( $headers ) {
    $this->headers = $headers;
}

public function get_header( $key ) {
    if ( isset( $this->headers[ strtolower( $key ) ] ) ) {
        return $this->headers[ strtolower( $key ) ];
    }

    return null;
}

public function set_header( $key, $value ) {
    $this->headers[ strtolower( $key ) ] = $value;
}

注意，get_header() 和 set_header() 在处理请求头名称时，会将其转换为小写，以确保大小写不敏感。

参数管理：get_params(), set_params(), get_param(), set_param()

参数是 HTTP 请求中携带的数据，它们可以通过 URL 查询字符串或请求体传递。 WP_REST_Request 提供了方法来管理这些参数：

• get_params(): 获取所有参数。
• set_params(): 设置所有参数，会覆盖已有的参数。
• get_param(): 获取指定名称的参数的值。
• set_param(): 设置指定名称的参数的值。

public function get_params() {
    return $this->params;
}

public function set_params( $params ) {
    $this->params = $params;
}

public function get_param( $key ) {
    if ( isset( $this->params[ $key ] ) ) {
        return $this->params[ $key ];
    }

    return null;
}

public function set_param( $key, $value ) {
    $this->params[ $key ] = $value;
}

参数合并：merge_params()

merge_params() 方法可以将新的参数合并到已有的参数中。如果新的参数和已有的参数有相同的名称，新的参数会覆盖已有的参数。

public function merge_params( $params ) {
    $this->params = array_merge( $this->params, $params );
}

属性管理：get_attributes(), set_attributes(), get_attribute(), set_attribute()

WP_REST_Request 还允许你设置一些额外的属性，用于存储一些请求相关的元数据。

• get_attributes(): 获取所有属性。
• set_attributes(): 设置所有属性，会覆盖已有的属性。
• get_attribute(): 获取指定名称的属性的值。
• set_attribute(): 设置指定名称的属性的值。

public function get_attributes() {
    return $this->attributes;
}

public function set_attributes( $attributes ) {
    $this->attributes = $attributes;
}

public function get_attribute( $key ) {
    if ( isset( $this->attributes[ $key ] ) ) {
        return $this->attributes[ $key ];
    }

    return null;
}

public function set_attribute( $key, $value ) {
    $this->attributes[ $key ] = $value;
}

实际应用：在 REST API 路由中使用 WP_REST_Request

现在我们来看一个实际的例子，演示如何在 REST API 路由中使用 WP_REST_Request 来获取请求参数。

<?php

add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/greet', array(
        'methods'  => 'GET',
        'callback' => 'my_plugin_greet',
    ) );
} );

function my_plugin_greet( WP_REST_Request $request ) {
    $name = $request->get_param( 'name' );

    if ( empty( $name ) ) {
        $name = 'World';
    }

    return 'Hello, ' . $name . '!';
}

在这个例子中，我们注册了一个 REST API 路由 /myplugin/v1/greet。 my_plugin_greet() 函数是路由的回调函数，它接收一个 WP_REST_Request 对象作为参数。

在 my_plugin_greet() 函数中，我们使用 $request->get_param( 'name' ) 来获取名为 name 的参数的值。 如果 name 参数为空，则默认使用 "World"。

现在，你可以通过以下 URL 发送请求：

/wp-json/myplugin/v1/greet?name=John

服务器会返回：

Hello, John!

如果没有传递 name 参数，比如：

/wp-json/myplugin/v1/greet

服务器会返回：

Hello, World!

高级用法：文件上传

WP_REST_Request 还可以用于处理文件上传。 但是，你需要注意的是，WordPress REST API 默认情况下不处理 multipart/form-data 请求。 你需要使用一些插件或自定义代码来处理文件上传。

总结：WP_REST_Request 的价值

WP_REST_Request 类是 WordPress REST API 的核心组件之一。 它封装了 HTTP 请求的所有信息，并提供了方便的接口来访问这些信息。 通过使用 WP_REST_Request，你可以轻松地构建强大的 REST API，从而实现各种复杂的功能。

注意事项：安全性和验证

在使用 WP_REST_Request 时，一定要注意安全性和数据验证。 永远不要信任用户输入的数据，要对所有参数进行验证和过滤，以防止安全漏洞。

结束语：请求的艺术

希望通过今天的讲解，你对 WP_REST_Request 类有了更深入的了解。 掌握 WP_REST_Request，你就掌握了与 WordPress REST API 交互的关键。 祝你在 WordPress REST API 的世界里玩得开心！咱们下期再见！