剖析 WordPress `rest_meta_query` 过滤器源码：如何处理 REST API 请求中的元数据查询。

大家好！欢迎来到今天的元数据查询深度解析讲座。今天我们要扒一扒 WordPress REST API 中一个相当关键的过滤器：rest_meta_query。这个过滤器允许我们自定义 REST API 请求中元数据的查询方式，让我们可以根据自己的需求进行更灵活的数据检索。准备好了吗？让我们一起深入源码，看看它到底是怎么工作的。

开场白：元数据，REST API 与我们的烦恼

想象一下，你正在构建一个基于 WordPress 的电商网站。你有很多商品，每个商品都有各种各样的元数据，比如颜色、尺寸、库存等等。现在，你想通过 REST API 提供一个接口，允许用户根据这些元数据来过滤商品。

问题来了：WordPress 默认的 REST API 可能不够灵活，无法满足你所有的元数据查询需求。例如，你可能需要进行范围查询（比如价格在 100 到 200 之间），或者进行模糊匹配（比如颜色包含“红”字的商品）。这时候，rest_meta_query 过滤器就派上用场了。

什么是 rest_meta_query 过滤器？

简单来说，rest_meta_query 是一个 WordPress 过滤器，它允许你修改 REST API 请求中用于生成元数据查询的参数。它拦截并修改 WP_Query 对象中关于元数据查询的部分，从而影响最终返回的结果。

源码剖析：rest_meta_query 的工作原理

要理解 rest_meta_query 的工作原理，我们需要先了解 WordPress REST API 如何处理元数据查询。

1. 接收请求参数： 当你通过 REST API 发起一个请求时，比如：

   /wp-json/wp/v2/posts?meta_key=price&meta_value=100&meta_compare=>=

   WordPress 会解析这些参数，并将它们传递给 WP_Query 对象。

2. 构建 WP_Query 对象： WP_Query 是 WordPress 中用于执行数据库查询的核心类。REST API 会根据请求参数构建一个 WP_Query 对象，其中就包括了元数据查询的部分。

3. 应用 rest_meta_query 过滤器： 在 WP_Query 对象被执行之前，rest_meta_query 过滤器会被应用。这意味着你可以通过这个过滤器来修改 WP_Query 对象中关于元数据查询的参数。

4. 执行查询： WP_Query 对象执行查询，并返回符合条件的文章。

源码示例：rest_meta_query 的应用

让我们来看一个具体的例子，假设我们需要实现一个自定义的元数据查询，允许用户根据价格范围来过滤商品。

首先，我们需要添加一个过滤器函数到 rest_meta_query：

add_filter( 'rest_meta_query', 'custom_rest_meta_query', 10, 2 );

function custom_rest_meta_query( $meta_query, $request ) {
  // 获取请求参数
  $price_min = $request->get_param( 'price_min' );
  $price_max = $request->get_param( 'price_max' );

  // 检查参数是否存在
  if ( ! empty( $price_min ) && ! empty( $price_max ) ) {
    // 构建自定义的元数据查询
    $meta_query[] = array(
      'key'     => 'price',
      'value'   => array( $price_min, $price_max ),
      'compare' => 'BETWEEN',
      'type'    => 'NUMERIC',
    );
  }

  return $meta_query;
}

这段代码做了什么？

• add_filter( 'rest_meta_query', 'custom_rest_meta_query', 10, 2 );: 注册一个过滤器，将 custom_rest_meta_query 函数添加到 rest_meta_query 过滤器链中。10 是优先级，2 是传递给过滤器的参数数量。
• custom_rest_meta_query( $meta_query, $request ): 这是我们的自定义过滤器函数。它接收两个参数：
  • $meta_query: 一个数组，包含了当前的元数据查询参数。这是我们修改的对象。
  • $request: 一个 WP_REST_Request 对象，包含了所有的请求参数。
• $request->get_param( 'price_min' ) 和 $request->get_param( 'price_max' ): 从请求中获取 price_min 和 price_max 参数。
• if ( ! empty( $price_min ) && ! empty( $price_max ) ): 确保两个参数都存在。
• 构建 $meta_query 数组: 如果参数存在，我们就构建一个新的元数据查询条件，并将其添加到 $meta_query 数组中。
  • 'key' => 'price': 指定要查询的元数据键为 price。
  • 'value' => array( $price_min, $price_max ): 指定要查询的值为一个数组，包含最小值和最大值。
  • 'compare' => 'BETWEEN': 指定比较方式为 BETWEEN，表示值在最小值和最大值之间。
  • 'type' => 'NUMERIC': 指定元数据类型为 NUMERIC，确保比较的是数值。
• return $meta_query: 返回修改后的 $meta_query 数组。

现在，你可以通过以下 REST API 请求来过滤商品：

/wp-json/wp/v2/posts?price_min=100&price_max=200

这个请求会返回所有价格在 100 到 200 之间的商品。

更高级的用法：动态比较运算符

上面的例子使用了固定的 BETWEEN 比较运算符。但如果我们想让用户可以指定比较运算符呢？比如，用户可以选择 >、<、>=、<= 等等。

我们可以修改一下上面的代码：

add_filter( 'rest_meta_query', 'custom_rest_meta_query', 10, 2 );

function custom_rest_meta_query( $meta_query, $meta_query_args, $request ) {
  // 获取请求参数
  $price_value = $request->get_param( 'price_value' );
  $price_compare = $request->get_param( 'price_compare' );

  // 检查参数是否存在
  if ( ! empty( $price_value ) && ! empty( $price_compare ) ) {
    // 验证比较运算符是否合法
    $allowed_compares = array( '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'REGEXP', 'NOT REGEXP', 'RLIKE' );
    if ( in_array( strtoupper( $price_compare ), $allowed_compares, true ) ) {
      // 构建自定义的元数据查询
      $meta_query[] = array(
        'key'     => 'price',
        'value'   => $price_value,
        'compare' => strtoupper( $price_compare ), // 转换为大写
        'type'    => 'NUMERIC',
      );
    } else {
      // 如果比较运算符不合法，可以返回一个错误
      return new WP_Error( 'invalid_meta_compare', 'Invalid meta compare operator.', array( 'status' => 400 ) );
    }
  }

  return $meta_query;
}

这段代码做了以下改进：

• 获取 $price_compare 参数: 从请求中获取 price_compare 参数，用于指定比较运算符。
• 验证比较运算符: 使用 $allowed_compares 数组验证 price_compare 参数是否合法。
• 使用 $price_compare 构建 $meta_query: 将 $price_compare 参数用于构建元数据查询。
• 错误处理: 如果 $price_compare 参数不合法，返回一个 WP_Error 对象，通知客户端请求错误。

现在，你可以通过以下 REST API 请求来过滤商品：

/wp-json/wp/v2/posts?price_value=100&price_compare=>=

这个请求会返回所有价格大于等于 100 的商品。

使用表格总结常用的 meta_query 参数

参数	描述	示例
key	要查询的元数据键。	'key' => 'price'
value	要查询的元数据值。	'value' => '100' 或者 'value' => array( '100', '200' )
compare	比较运算符。	'compare' => '='，'compare' => 'BETWEEN'，'compare' => 'LIKE' 等等
type	元数据类型。	'type' => 'NUMERIC'，'type' => 'CHAR'，'type' => 'DATE' 等等
relation	当有多个元数据查询条件时，指定它们之间的关系（AND 或 OR）。	'relation' => 'AND'
meta_exists	检查是否存在具有给定键的元数据。 值为 true 或 false。	'meta_exists' => true
meta_not_exists	检查是否不存在具有给定键的元数据。 值为 true 或 false。	'meta_not_exists' => true

注意事项

• 安全性: 在使用 rest_meta_query 过滤器时，务必对用户输入进行验证和过滤，以防止 SQL 注入攻击。
• 性能: 复杂的元数据查询可能会影响性能。尽量避免使用过于复杂的查询条件，并对数据库进行适当的优化。
• 数据类型: 确保元数据类型与查询条件匹配。例如，如果要比较数值，应该将元数据类型设置为 NUMERIC。
• REST API 版本: rest_meta_query 过滤器的行为可能因 WordPress REST API 版本而异。请参考官方文档了解具体细节。

实战案例：模糊匹配商品名称

假设我们需要实现一个功能，允许用户根据商品名称进行模糊匹配。我们可以使用 LIKE 比较运算符来实现：

add_filter( 'rest_meta_query', 'custom_rest_meta_query', 10, 2 );

function custom_rest_meta_query( $meta_query, $request ) {
  // 获取请求参数
  $product_name = $request->get_param( 'product_name' );

  // 检查参数是否存在
  if ( ! empty( $product_name ) ) {
    // 构建自定义的元数据查询
    $meta_query[] = array(
      'key'     => 'product_name',
      'value'   => '%' . sanitize_text_field( $product_name ) . '%', // 添加通配符
      'compare' => 'LIKE',
    );
  }

  return $meta_query;
}

在这个例子中，我们使用了 LIKE 比较运算符，并在 $product_name 的前后添加了 % 通配符，表示模糊匹配。sanitize_text_field() 函数用于对用户输入进行清理，防止 XSS 攻击。

你可以通过以下 REST API 请求来过滤商品：

/wp-json/wp/v2/posts?product_name=红

这个请求会返回所有商品名称包含“红”字的商品。

总结

rest_meta_query 过滤器是一个强大的工具，可以让你自定义 WordPress REST API 中元数据的查询方式。通过它可以实现各种各样的查询需求，例如范围查询、模糊匹配、动态比较运算符等等。但要注意，在使用它的时候，务必注意安全性和性能问题，并对用户输入进行验证和过滤。

希望今天的讲座对你有所帮助！记住，源码是最好的老师，多看、多练，你也能成为元数据查询大师！

互动环节

大家有什么问题吗？欢迎提问！