分析 WordPress 在 REST API 中的 schema 自动推导机制 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

WordPress REST API Schema 自动推导机制：一场深度剖析

各位朋友，大家好！今天我们来聊聊 WordPress REST API 中一个非常重要的特性：Schema 自动推导机制。这个机制让 WordPress REST API 在提供强大功能的同时，也保持了较高的灵活性和易用性。我们将深入探讨其原理、实现方式以及如何利用它来构建更健壮的 API 应用。

什么是 Schema？为何需要 Schema 自动推导？

在深入讨论自动推导之前，我们首先要理解什么是 Schema，以及它在 REST API 中扮演的角色。Schema 本质上是对数据结构的一种描述，它定义了数据的类型、格式、允许的值以及其他约束条件。

在 REST API 的上下文中，Schema 用于描述 API 资源（如文章、页面、用户等）的结构。它告诉客户端 API 返回的数据长什么样，以及客户端应该如何构造请求数据。

举个例子，假设我们有一个表示文章的 API 资源，其 Schema 可能如下所示（简化版）：

{
  "title": "Post",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Unique identifier for the post."
    },
    "title": {
      "type": "string",
      "description": "The title for the post."
    },
    "content": {
      "type": "string",
      "description": "The content for the post."
    },
    "date": {
      "type": "string",
      "format": "date-time",
      "description": "The date the post was published."
    }
  }
}

这个 Schema 告诉我们：

API 返回的是一个对象 (type": "object")。
这个对象包含 id、title、content 和 date 四个属性。
每个属性都有明确的数据类型 (integer, string, date-time) 和描述。

有了 Schema，客户端就可以：

验证 API 返回的数据是否符合预期。
自动生成客户端代码（例如，根据 Schema 生成 TypeScript 接口）。
在发送请求之前验证请求数据的格式是否正确。
生成 API 文档，方便开发者使用。

为什么要自动推导？

手动编写 Schema 是一项繁琐且容易出错的任务。特别是对于 WordPress 这样的 CMS 系统，其数据模型非常复杂，且可以通过插件和主题进行扩展。如果每次数据模型发生变化，都需要手动更新 Schema，那将是一场噩梦。

Schema 自动推导的目标是：根据 WordPress 的数据模型，自动生成 REST API 的 Schema。 这样，我们就可以避免手动编写和维护 Schema 的麻烦，并确保 Schema 始终与数据模型保持同步。

WordPress Schema 自动推导的原理

WordPress REST API 的 Schema 自动推导机制主要依赖于以下几个核心概念：

注册 REST API 路由： 使用 register_rest_route() 函数注册 API 路由，并指定处理请求的回调函数。
定义 Schema 回调函数： 为每个 API 路由指定一个 Schema 回调函数。这个函数负责生成该路由的 Schema。
使用 WP_REST_Controller 类： 大多数 REST API 控制器都继承自 WP_REST_Controller 类。这个类提供了一些辅助方法，方便我们生成 Schema。
利用 WordPress 的数据模型： Schema 自动推导机制会利用 WordPress 现有的数据模型（例如，文章类型、字段、分类法等）来生成 Schema。

下面我们以一个自定义文章类型的 API 路由为例，来具体说明 Schema 自动推导的流程。

假设我们有一个自定义文章类型 book，它包含 title、author 和 publication_date 三个字段。

1. 注册 API 路由：

add_action( 'rest_api_init', function () {
  register_rest_route( 'my-plugin/v1', '/books/(?P<id>d+)', array(
    'methods'  => 'GET',
    'callback' => 'get_book',
    'permission_callback' => '__return_true', // 允许任何人访问
    'args' => array(
        'id' => array(
            'validate_callback' => 'rest_validate_request_arg',
            'sanitize_callback' => 'absint',
        ),
    ),
    'schema'   => 'get_book_schema', // 指定 Schema 回调函数
  ) );
} );

在这个例子中，我们使用 register_rest_route() 函数注册了一个 API 路由 /my-plugin/v1/books/(?P<id>d+)，用于获取指定 ID 的 book。schema 参数指定了 get_book_schema 函数作为该路由的 Schema 回调函数。

2. 定义 Schema 回调函数：

function get_book_schema() {
  $schema = array(
    'schema' => array(
      '$schema'    => 'http://json-schema.org/draft-04/schema#',
      'title'      => 'Book',
      'type'       => 'object',
      'properties' => array(
        'id' => array(
          'type'        => 'integer',
          'description' => __( 'Unique identifier for the book.', 'my-plugin' ),
          'context'     => array( 'view', 'edit', 'embed' ),
          'readonly'    => true,
        ),
        'title' => array(
          'type'        => 'string',
          'description' => __( 'The title of the book.', 'my-plugin' ),
          'context'     => array( 'view', 'edit', 'embed' ),
        ),
        'author' => array(
          'type'        => 'string',
          'description' => __( 'The author of the book.', 'my-plugin' ),
          'context'     => array( 'view', 'edit', 'embed' ),
        ),
        'publication_date' => array(
          'type'        => 'string',
          'format'      => 'date',
          'description' => __( 'The publication date of the book.', 'my-plugin' ),
          'context'     => array( 'view', 'edit', 'embed' ),
        ),
      ),
    ),
  );
  return $schema;
}

get_book_schema 函数返回一个数组，这个数组会被转换为 JSON Schema。我们定义了 id、title、author 和 publication_date 四个属性，并指定了它们的数据类型、描述信息和上下文。

3. 使用 WP_REST_Controller (可选):

虽然我们上面的例子没有使用 WP_REST_Controller，但它通常是一个更好的选择，特别是对于更复杂的 API。 WP_REST_Controller 提供了一些方便的方法来生成 Schema，并处理常见的 API 操作。

class My_REST_Books_Controller extends WP_REST_Controller {

  protected $namespace = 'my-plugin/v1';
  protected $rest_base = 'books';

  public function register_routes() {
    register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P<id>d+)', array(
      array(
        'methods'             => WP_REST_Server::READABLE,
        'callback'            => array( $this, 'get_item' ),
        'permission_callback' => array( $this, 'get_item_permissions_check' ),
        'args'                => array(
          'context' => $this->get_context_param( array( 'default' => 'view' ) ),
        ),
      ),
      'schema' => array( $this, 'get_item_schema' ),
    ) );
  }

  public function get_item_schema() {
    $schema = array(
      '$schema'    => 'http://json-schema.org/draft-04/schema#',
      'title'      => 'Book',
      'type'       => 'object',
      'properties' => array(
        'id' => array(
          'type'        => 'integer',
          'description' => __( 'Unique identifier for the book.', 'my-plugin' ),
          'context'     => array( 'view', 'edit', 'embed' ),
          'readonly'    => true,
        ),
        'title' => array(
          'type'        => 'string',
          'description' => __( 'The title of the book.', 'my-plugin' ),
          'context'     => array( 'view', 'edit', 'embed' ),
        ),
        'author' => array(
          'type'        => 'string',
          'description' => __( 'The author of the book.', 'my-plugin' ),
          'context'     => array( 'view', 'edit', 'embed' ),
        ),
        'publication_date' => array(
          'type'        => 'string',
          'format'      => 'date',
          'description' => __( 'The publication date of the book.', 'my-plugin' ),
          'context'     => array( 'view', 'edit', 'embed' ),
        ),
      ),
    );
    return $schema;
  }

  public function get_item( $request ) {
    // 获取 book 数据的逻辑
    $book_id = (int) $request['id'];
    $book_data = get_post( $book_id ); // 假设 book 是一个 post 类型
    if ( empty( $book_data ) ) {
      return new WP_Error( 'rest_book_invalid_id', __( 'Invalid book ID.', 'my-plugin' ), array( 'status' => 404 ) );
    }
    $data = $this->prepare_item_for_response( $book_data, $request );
    return rest_ensure_response( $data );
  }

  public function prepare_item_for_response( $item, $request ) {
    $data = array(
      'id'               => $item->ID,
      'title'            => get_the_title( $item->ID ),
      'author'           => get_post_meta( $item->ID, 'author', true ), // 假设作者信息存储在 post meta 中
      'publication_date' => get_post_meta( $item->ID, 'publication_date', true ), // 假设发布日期存储在 post meta 中
    );
    $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
    $data = $this->filter_response_by_context( $data, $context );
    $data = $this->add_additional_fields_to_object( $data, $request );
    $data = $this->add_links( $data );
    return $data;
  }

  public function get_item_permissions_check( $request ) {
    // 权限检查逻辑
    return true; // 允许任何人访问
  }

  protected function add_links( $data ) {
    $links = array(
      'self' => array(
        'href' => rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $data['id'] ) ),
      ),
      'collection' => array(
        'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),
      ),
    );
    $data['_links'] = $links;
    return $data;
  }
}

add_action( 'rest_api_init', function () {
  $controller = new My_REST_Books_Controller();
  $controller->register_routes();
} );

在这个例子中：

我们定义了一个 My_REST_Books_Controller 类，它继承自 WP_REST_Controller。
register_routes() 方法注册了 API 路由，并将 get_item_schema 方法指定为 Schema 回调函数。
get_item_schema() 方法与之前的例子相同，负责生成 Schema。
get_item() 方法处理 GET 请求，获取指定 ID 的 book 数据。
prepare_item_for_response() 方法将从数据库中获取的原始数据转换为 API 响应的格式。

4. 利用 WordPress 的数据模型：

WordPress 提供了一系列函数和钩子，方便我们访问和操作数据模型。我们可以利用这些函数来动态生成 Schema。

例如，我们可以使用 get_post_types() 函数获取所有已注册的文章类型，并根据文章类型的元数据（例如，支持的字段、分类法等）来生成 Schema。

function get_all_post_types_schema() {
  $schema = array(
    'schema' => array(
      '$schema'    => 'http://json-schema.org/draft-04/schema#',
      'title'      => 'Post Types',
      'type'       => 'array',
      'items' => array(
        'type' => 'object',
        'properties' => array(), // 稍后填充
      ),
    ),
  );

  $post_types = get_post_types( array( 'show_in_rest' => true ), 'objects' );

  foreach ( $post_types as $post_type ) {
    $properties = array(
      'name' => array(
        'type'        => 'string',
        'description' => __( 'The name of the post type.', 'my-plugin' ),
        'context'     => array( 'view', 'edit', 'embed' ),
        'readonly'    => true,
      ),
      'label' => array(
        'type'        => 'string',
        'description' => __( 'The label of the post type.', 'my-plugin' ),
        'context'     => array( 'view', 'edit', 'embed' ),
      ),
      // 可以添加更多属性，例如支持的字段、分类法等
    );

    // 将属性添加到 schema 中
    $schema['schema']['items']['properties'][$post_type->name] = array(
      'type' => 'object',
      'properties' => $properties,
    );
  }

  return $schema;
}

这个例子演示了如何根据 get_post_types() 函数返回的文章类型信息，动态生成 Schema。我们可以根据需要添加更多属性，例如支持的字段、分类法等。

Schema 的上下文 (Context)

在上面的例子中，我们看到了 context 属性。 Schema 的上下文是一个重要的概念，它允许我们根据不同的使用场景，返回不同版本的 Schema。

常见的上下文包括：

view：用于查看资源。
edit：用于编辑资源。
embed：用于嵌入资源。

例如，对于 view 上下文，我们可能只需要返回资源的摘要信息，而对于 edit 上下文，我们需要返回资源的完整信息，包括所有可编辑的字段。

我们可以使用 $this->filter_response_by_context() 方法来根据上下文过滤 Schema 中的属性。

public function prepare_item_for_response( $item, $request ) {
  $data = array(
    'id'               => $item->ID,
    'title'            => get_the_title( $item->ID ),
    'author'           => get_post_meta( $item->ID, 'author', true ),
    'publication_date' => get_post_meta( $item->ID, 'publication_date', true ),
    'secret_field'     => 'This is a secret!', // 仅在 edit 上下文中显示
  );

  $context = ! empty( $request['context'] ) ? $request['context'] : 'view';

  // 根据上下文过滤数据
  $data = $this->filter_response_by_context( $data, $context );

  return rest_ensure_response( $data );
}

在 Schema 中，我们可以通过 context 属性来指定属性在哪些上下文中显示。

'secret_field' => array(
  'type'        => 'string',
  'description' => __( 'A secret field.', 'my-plugin' ),
  'context'     => array( 'edit' ), // 仅在 edit 上下文中显示
),

Schema 自动推导的局限性

虽然 WordPress 的 Schema 自动推导机制非常强大，但它并非万能的。在某些情况下，我们可能需要手动编写 Schema，或者对自动推导的 Schema 进行修改。

以下是一些 Schema 自动推导的局限性：

复杂的数据结构： 对于非常复杂的数据结构，自动推导可能无法生成完全准确的 Schema。
动态字段： 如果数据模型包含动态字段（例如，根据用户权限动态显示的字段），自动推导可能无法处理。
自定义验证规则： 如果需要使用自定义验证规则，我们需要手动编写 Schema。

在这些情况下，我们需要根据具体情况，选择合适的方法来生成 Schema。

代码案例：利用 WordPress Metadata API 推导Schema

以下代码展示了如何利用 WordPress Metadata API 自动推导 Schema，特别是针对存储在 post metadata 中的自定义字段。

function get_book_schema_from_metadata() {
    $schema = array(
        'schema' => array(
            '$schema'    => 'http://json-schema.org/draft-04/schema#',
            'title'      => 'Book (Metadata Driven)',
            'type'       => 'object',
            'properties' => array(
                'id' => array(
                    'type'        => 'integer',
                    'description' => __( 'Unique identifier for the book.', 'my-plugin' ),
                    'context'     => array( 'view', 'edit', 'embed' ),
                    'readonly'    => true,
                ),
            ),
        ),
    );

    $post_id = 1; // 假设我们有一个示例 post ID。实际应用中需要动态获取。
    $metadata = get_post_meta( $post_id );

    foreach ( $metadata as $key => $values ) {
        // 跳过以下划线开头的元数据 (通常是内部字段)
        if ( strpos( $key, '_' ) === 0 ) {
            continue;
        }

        // 简单地假设所有元数据都是字符串类型. 更复杂的逻辑可能需要根据实际数据进行类型推断.
        $schema['schema']['properties'][$key] = array(
            'type'        => 'string',
            'description' => sprintf( __( 'Metadata field: %s', 'my-plugin' ), $key ),
            'context'     => array( 'view', 'edit', 'embed' ),
        );
    }

    return $schema;
}

这段代码首先定义了一个基本的 Schema 结构，包含 id 字段。然后，它使用 get_post_meta() 函数获取指定 post 的所有 metadata。遍历 metadata，为每个 metadata 字段创建一个 Schema 属性，并假设其类型为字符串。

更高级的类型推断:

为了更准确地推断数据类型，我们可以尝试以下方法：

检查值的格式: 例如，如果值看起来像一个日期，我们可以将其类型设置为 string 并指定 format 为 date 或 date-time。
使用自定义字段插件的 API: 许多自定义字段插件提供 API，允许我们获取字段的类型信息。
存储类型信息: 可以在 metadata 中存储字段的类型信息，并在生成 Schema 时使用这些信息。

总结与思考

WordPress REST API 的 Schema 自动推导机制是一个强大的工具，可以帮助我们构建更健壮、更易于维护的 API 应用。理解其原理和局限性，并根据具体情况选择合适的方法来生成 Schema，是每个 WordPress 开发者都应该掌握的技能。通过动态生成 API Schema，WordPress 能够更好地适应不断变化的数据模型，为开发者提供更灵活的 API 体验。最终，这将有助于构建更强大的 WordPress 应用生态系统。