阐述 WordPress `WP_REST_Request` 类的源码：如何通过 `get_param()` 方法安全地获取请求参数。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

大家好，欢迎来到今天的“WordPress REST API 深潜”讲座。今天我们来聊聊 WP_REST_Request 类的核心之一：get_param() 方法。这可是个安全地从 REST 请求中提取参数的利器，用不好可能会被黑客叔叔请喝茶哦！

开场白：为什么我们需要 get_param()？

想象一下，你正在开发一个 WordPress 插件，允许用户通过 REST API 创建新的帖子。用户需要提供帖子的标题、内容等等。这些信息通过 HTTP 请求发送过来，可能是 GET 请求的 URL 参数，也可能是 POST 请求的请求体。

直接从 $_GET 或 $_POST 数组中获取数据？嗯… 风险有点大。

不安全： 用户可以随便修改这些数据，注入恶意代码，比如 JavaScript 脚本 (XSS 攻击) 或者 SQL 注入。
类型不明确： 传入的都是字符串，你需要自己做类型转换，否则可能会出现各种奇怪的 Bug。
缺少验证： 你需要手动检查数据是否符合预期，比如标题不能为空，内容长度不能超过限制等等。

WP_REST_Request 类的 get_param() 方法就是为了解决这些问题而生的。它提供了一层安全保护，帮你处理数据清洗、类型转换和验证，让你更专注于业务逻辑。

WP_REST_Request 类简介

首先，我们来简单了解一下 WP_REST_Request 类。这是 WordPress REST API 的核心类之一，代表了一个 REST 请求。它封装了请求的各种信息，包括：

请求方法 (GET, POST, PUT, DELETE 等)
请求参数 (URL 参数和请求体参数)
请求头
请求路径
等等…

你可以通过 WP_REST_Request 对象访问这些信息，并对请求进行处理。

get_param() 方法：安全取参的正确姿势

get_param() 方法的原型如下：

public function get_param( $param ) {
    // ... 代码 ...
}

它接受一个参数 $param，表示你要获取的参数的名称。如果参数存在，它会返回参数的值；如果参数不存在，则返回 null。

源码剖析：get_param() 的内部机制

让我们深入 get_param() 方法的源码，看看它是如何工作的：

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

        if ( isset( $this->params['POST'][ $param ] ) ) {
            return $this->params['POST'][ $param ];
        }

        if ( isset( $this->params['FILES'][ $param ] ) ) {
            return $this->params['FILES'][ $param ];
        }

        return null;
    }

这段代码很简单，但却很关键。它按照以下顺序查找参数：

GET 参数： 首先检查 $_GET 参数，存储在 $this->params['GET'] 中。
POST 参数： 如果 GET 参数中没有找到，就检查 $_POST 参数，存储在 $this->params['POST'] 中。
FILES 参数： 接着检查 $_FILES 参数，存储在 $this->params['FILES'] 中，主要用于文件上传。
返回 null： 如果以上都没有找到，就返回 null，表示参数不存在。

注意： get_param() 方法本身 不进行任何数据清洗、类型转换或验证。它只是简单地从请求中提取参数的值。这些工作需要在其他地方完成，比如在你的路由回调函数中。

使用示例：从 REST 请求中获取数据

假设我们有一个 REST 路由，用于更新帖子的标题：

add_action( 'rest_api_init', function () {
    register_rest_route( 'my-plugin/v1', '/posts/(?P<id>d+)', array(
        'methods'  => 'PUT',
        'callback' => 'my_plugin_update_post',
        'args'     => array(
            'id'    => array(
                'validate_callback' => 'rest_validate_request_arg',
                'sanitize_callback' => 'absint',
            ),
            'title' => array(
                'validate_callback' => 'my_plugin_validate_title',
                'sanitize_callback' => 'sanitize_text_field',
                'required'          => true,
            ),
        ),
    ) );
} );

function my_plugin_update_post( WP_REST_Request $request ) {
    $post_id = $request->get_param( 'id' );
    $title   = $request->get_param( 'title' );

    if ( ! get_post( $post_id ) ) {
        return new WP_Error( 'post_not_found', 'Post not found', array( 'status' => 404 ) );
    }

    $updated = wp_update_post( array(
        'ID'         => $post_id,
        'post_title' => $title,
    ) );

    if ( is_wp_error( $updated ) ) {
        return $updated;
    }

    return rest_ensure_response( get_post( $post_id ) );
}

function my_plugin_validate_title( $value, $request, $param ) {
    if ( empty( $value ) ) {
        return new WP_Error( 'rest_invalid_param', 'Title cannot be empty', array( 'status' => 400 ) );
    }

    if ( strlen( $value ) > 255 ) {
        return new WP_Error( 'rest_invalid_param', 'Title cannot be longer than 255 characters', array( 'status' => 400 ) );
    }

    return true;
}

在这个例子中：

register_rest_route() 函数注册了一个 REST 路由，用于处理 PUT 请求。
my_plugin_update_post() 函数是路由的回调函数，它负责处理请求。
$request->get_param( 'id' ) 和 $request->get_param( 'title' ) 从请求中获取 id 和 title 参数。
rest_validate_request_arg 和 my_plugin_validate_title 函数用于验证参数的有效性。
absint 和 sanitize_text_field 函数用于清洗参数，防止恶意代码注入。

参数注册：args 数组的力量

在 register_rest_route() 函数中，我们使用 args 数组来定义参数的验证和清洗规则。这是一个非常重要的步骤，它可以帮助你提高 API 的安全性。

args 数组的结构如下：

'args' => array(
    'parameter_name' => array(
        'validate_callback' => 'validation_function',
        'sanitize_callback' => 'sanitization_function',
        'required'          => true, // or false
        'default'           => 'default_value',
        'description'       => 'Parameter description',
    ),
    // ... more parameters
),

参数名称	描述
`validate_callback`	用于验证参数的函数。该函数接收参数的值、`WP_REST_Request` 对象和参数名称作为参数。如果参数有效，则返回 `true`；否则，返回 `WP_Error` 对象。
`sanitize_callback`	用于清洗参数的函数。该函数接收参数的值作为参数，并返回清洗后的值。
`required`	布尔值，表示参数是否必须。如果设置为 `true`，则如果参数不存在，请求将失败。
`default`	参数的默认值。如果参数不存在，则使用此值。
`description`	参数的描述。这可以用于生成 API 文档。
`type`	参数的类型。可以是 ‘string’, ‘integer’, ‘number’, ‘boolean’, ‘array’, ‘object’。这可以用于生成 API 文档和客户端代码。

常用的验证和清洗函数

WordPress 提供了一些常用的验证和清洗函数，你可以直接使用：

验证函数：
- rest_validate_request_arg(): 基本的验证函数，可以检查参数是否为空。
- is_email(): 验证参数是否是有效的电子邮件地址。
- is_numeric(): 验证参数是否是数字。
- absint(): 验证参数是否是正整数。
- 你也可以自定义验证函数，例如 my_plugin_validate_title()。
清洗函数：
- sanitize_text_field(): 去除 HTML 标签和编码特殊字符，用于清洗文本字段。
- sanitize_email(): 清洗电子邮件地址。
- absint(): 将参数转换为正整数。
- esc_url_raw(): 清洗 URL。
- wp_kses_post(): 允许有限的 HTML 标签，适用于内容字段。

最佳实践：安全第一，永远不要相信用户输入

以下是一些使用 get_param() 方法的最佳实践：

始终验证和清洗用户输入： 不要相信用户发送的任何数据。使用 validate_callback 和 sanitize_callback 选项来验证和清洗参数。
使用强类型： 尽可能使用强类型，例如整数、浮点数、布尔值等。这可以帮助你避免类型错误和安全漏洞。
限制参数长度： 限制参数的长度，防止缓冲区溢出攻击。
使用白名单： 只允许特定的 HTML 标签和属性，防止 XSS 攻击。
记录所有请求： 记录所有 REST 请求，以便进行审计和安全分析。

总结：get_param() 是你的好朋友

WP_REST_Request 类的 get_param() 方法是 WordPress REST API 开发中一个非常重要的工具。它可以帮助你安全地从 REST 请求中提取参数，并提高 API 的安全性。记住，安全第一，永远不要相信用户输入。通过合理使用 get_param() 方法和相关的验证和清洗函数，你可以构建安全可靠的 REST API。

高级技巧：超越 get_param()

虽然 get_param() 很好用，但有时候我们需要更高级的功能。

get_body() 和 get_json_params(): 如果你的请求体是 JSON 格式，可以使用 get_body() 获取原始 JSON 字符串，然后使用 get_json_params() 将其解析为数组。
自定义参数处理: 你可以通过扩展 WP_REST_Request 类来添加自定义的参数处理逻辑。

问答环节

现在，欢迎大家提问，我会尽力解答。例如：

get_param() 和 $_GET/$_POST 相比，优势在哪里？
如何自定义验证函数？
如何处理文件上传？
如何处理复杂的数据结构？

希望今天的讲座对大家有所帮助！感谢各位的聆听。

发表回复 取消回复

发表回复取消回复