WordPress源码深度解析之：古腾堡的`REST API`：`REST`端点在块编辑器中的应用。

各位好，欢迎来到今天的“WordPress源码深度解析”小课堂！今天咱们聊点刺激的——古腾堡的REST API，看看它在块编辑器里是怎么翻江倒海的。别怕，咱们不搞那些云里雾里的概念，直接上代码，保证你听得懂，学得会，用得上。

一、REST API：古腾堡的沟通桥梁

首先，得简单说说REST API是个啥玩意儿。想象一下，古腾堡编辑器就像一个精明的建筑师，而WordPress的数据库就像一个堆满砖瓦的仓库。建筑师要盖房子，总不能自己跑去仓库一块块搬砖吧？这时候就需要一个中间人——REST API，它负责接收建筑师的指令（请求），然后从仓库里搬出相应的砖瓦（数据），再交给建筑师。

简单来说，REST API就是一套规则，让不同的系统（比如古腾堡编辑器和WordPress后端）可以用统一的方式进行交流。它基于HTTP协议，使用常见的GET、POST、PUT、DELETE等方法来操作数据。

二、古腾堡与REST API：一场双向奔赴的爱情

古腾堡编辑器几乎所有的数据交互都离不开REST API。它用REST API来获取文章、页面、分类目录、标签、用户等等，甚至保存文章内容也是通过REST API完成的。

举个例子，当你打开古腾堡编辑器，想插入一个图片块时，编辑器会通过REST API向WordPress后端请求媒体库里的图片列表。这个请求看起来大概是这样的：

// JavaScript 代码 (在古腾堡编辑器中运行)
fetch( wp.rest.api.root + 'wp/v2/media?per_page=10' ) // 获取媒体库前10张图片
    .then( response => response.json() )
    .then( images => {
        // 处理图片数据，比如显示在图片选择器中
        console.log(images);
    });

这段代码使用了JavaScript的fetch API，向wp/v2/media端点发送了一个GET请求。 wp.rest.api.root 是WordPress REST API的根路径，通常是你的网站地址加上/wp-json/。 wp/v2/media 是媒体库的REST API端点。 per_page=10 是一个参数，告诉服务器每次返回10张图片。

后端收到这个请求后，会查询数据库，找到符合条件的图片数据，然后以JSON格式返回给编辑器。编辑器拿到数据后，就可以把图片显示在图片选择器里，让你选择要插入的图片了。

三、核心端点：古腾堡的常用工具

古腾堡编辑器依赖于很多REST API端点，其中一些核心的端点包括：

端点	方法	描述
/wp/v2/posts	GET, POST, PUT, DELETE	处理文章，包括获取、创建、更新和删除文章
/wp/v2/pages	GET, POST, PUT, DELETE	处理页面，功能同上
/wp/v2/media	GET, POST, PUT, DELETE	处理媒体文件，包括获取、上传、更新和删除媒体文件
/wp/v2/categories	GET, POST, PUT, DELETE	处理文章分类目录
/wp/v2/tags	GET, POST, PUT, DELETE	处理文章标签
/wp/v2/users	GET	获取用户信息
/wp/v2/blocks	GET	获取注册的块的信息
/wp/v2/block-types	GET	获取块类型信息
/wp/v2/settings	GET, POST	获取和更新站点设置

这些端点都是以/wp/v2/开头的，这是WordPress REST API的默认版本。每个端点都支持不同的HTTP方法，用于执行不同的操作。

四、自定义端点：扩展古腾堡的能力

WordPress允许开发者自定义REST API端点，这为扩展古腾堡编辑器的功能提供了无限可能。比如，你可以创建一个自定义端点来获取特定类型的数据，或者执行一些自定义的操作。

下面是一个简单的例子，演示如何创建一个自定义REST API端点，用于获取最近发布的5篇文章：

<?php
// PHP 代码 (放在你的主题或插件的 functions.php 文件中)
add_action( 'rest_api_init', function () {
  register_rest_route( 'my-plugin/v1', '/recent-posts', array(
    'methods'  => 'GET',
    'callback' => 'my_plugin_get_recent_posts',
  ) );
} );

function my_plugin_get_recent_posts( WP_REST_Request $request ) {
  $args = array(
    'posts_per_page' => 5,
  );

  $posts = get_posts( $args );

  if ( empty( $posts ) ) {
    return new WP_Error( 'no_posts', 'No posts found', array( 'status' => 404 ) );
  }

  $data = array();
  foreach ( $posts as $post ) {
    $data[] = array(
      'id'    => $post->ID,
      'title' => $post->post_title,
      'link'  => get_permalink( $post ),
    );
  }

  return rest_ensure_response( $data );
}
?>

这段代码使用了register_rest_route函数来注册一个自定义REST API端点。

• 'my-plugin/v1' 是命名空间，用于区分不同的插件或主题的端点。
• '/recent-posts' 是端点的路径。
• 'methods' => 'GET' 指定了该端点只接受GET请求。
• 'callback' => 'my_plugin_get_recent_posts' 指定了处理请求的回调函数。

my_plugin_get_recent_posts函数负责查询最近发布的5篇文章，然后将结果格式化成JSON数据返回。 rest_ensure_response函数确保返回的是一个标准的REST API响应对象。

在古腾堡编辑器中，你可以使用fetch API来调用这个自定义端点：

// JavaScript 代码 (在古腾堡编辑器中运行)
fetch( wp.rest.api.root + 'my-plugin/v1/recent-posts' )
    .then( response => response.json() )
    .then( posts => {
        // 处理文章数据，比如显示在编辑器中
        console.log(posts);
    });

这样，你就可以在古腾堡编辑器中获取到最近发布的5篇文章的数据了。你可以根据自己的需求，修改my_plugin_get_recent_posts函数，返回不同的数据，或者执行不同的操作。

五、块的属性与REST API：数据流动的通道

块的属性（Attributes）是块的核心组成部分，它们定义了块的数据结构。古腾堡编辑器使用REST API来存储和检索块的属性值。

当你保存一篇文章时，古腾堡编辑器会将文章内容转换成一个JSON对象，其中包含了每个块的属性值。然后，编辑器会通过REST API将这个JSON对象保存到数据库中。

例如，一个简单的文本块可能包含一个content属性，用于存储文本内容。当你编辑文本块的内容时，编辑器会更新content属性的值。当你保存文章时，新的content属性值会被保存到数据库中。

// 块的定义 (JavaScript)
registerBlockType( 'my-plugin/text-block', {
    title: 'Text Block',
    icon: 'edit',
    category: 'common',
    attributes: {
        content: {
            type: 'string',
            default: '',
        },
    },
    edit: ( props ) => {
        const { attributes, setAttributes } = props;
        const { content } = attributes;

        return (
            <RichText
                tagName="p"
                value={ content }
                onChange={ ( newContent ) => setAttributes( { content: newContent } ) }
            />
        );
    },
    save: ( props ) => {
        const { attributes } = props;
        const { content } = attributes;

        return (
            <p>
                { content }
            </p>
        );
    },
} );

在这个例子中，content属性的类型是string，默认值是空字符串。 edit 函数定义了块的编辑界面，使用了 RichText 组件来编辑文本内容。 onChange 事件处理器负责更新 content 属性的值。 save 函数定义了块的保存方式，将 content 属性的值渲染成一个 <p> 标签。

当你保存文章时，古腾堡编辑器会将 content 属性的值保存到数据库中。当你再次打开文章时，编辑器会从数据库中检索 content 属性的值，并将其显示在编辑界面中。

六、高级应用：与REST API深度交互

除了基本的CRUD操作，古腾堡编辑器还可以与REST API进行更深度的交互。比如，你可以使用REST API来实现以下功能：

• 动态数据加载： 使用REST API从外部数据源加载数据，并将其显示在块中。例如，你可以创建一个块，从一个天气API获取天气数据，并将其显示在文章中。
• 自定义验证： 使用REST API来实现自定义的验证规则。例如，你可以创建一个自定义端点，用于验证用户输入的邮箱地址是否有效。
• 异步操作： 使用REST API来执行一些耗时的异步操作，比如图片压缩或视频转码。

七、安全注意事项：守护数据的安全

在使用REST API时，安全性是一个非常重要的问题。你需要采取一些措施来保护你的数据，防止未经授权的访问。

• 权限控制： 使用WordPress的权限系统来控制用户对REST API端点的访问权限。例如，你可以只允许管理员访问某些端点。
• 数据验证： 对所有通过REST API接收到的数据进行验证，防止恶意数据注入。
• 使用HTTPS： 使用HTTPS协议来加密REST API的通信，防止数据被窃听。
• Nonce验证： 使用Nonce验证来防止跨站请求伪造（CSRF）攻击。

八、调试技巧：排查错误的利器

在开发过程中，难免会遇到各种各样的问题。掌握一些调试技巧可以帮助你快速找到问题所在。

• 使用浏览器的开发者工具： 浏览器的开发者工具可以帮助你查看REST API的请求和响应，以及JavaScript代码的执行情况。
• 使用WordPress的调试模式： 启用WordPress的调试模式可以显示PHP错误和警告信息。
• 使用插件： 有一些插件可以帮助你调试REST API，比如REST API Toolbox。

九、代码示例：一个完整的自定义块

为了让你更好地理解古腾堡编辑器与REST API的交互，这里提供一个完整的自定义块的代码示例。这个块可以从一个自定义的REST API端点获取数据，并将其显示在文章中。

首先，我们需要创建一个自定义的REST API端点：

<?php
// PHP 代码 (放在你的主题或插件的 functions.php 文件中)
add_action( 'rest_api_init', function () {
  register_rest_route( 'my-plugin/v1', '/my-data', array(
    'methods'  => 'GET',
    'callback' => 'my_plugin_get_my_data',
  ) );
} );

function my_plugin_get_my_data( WP_REST_Request $request ) {
  // 模拟数据
  $data = array(
    'title' => 'Hello World',
    'content' => 'This is my custom data.',
  );

  return rest_ensure_response( $data );
}
?>

这个端点返回一个包含title和content属性的JSON对象。

接下来，我们需要创建一个自定义的块：

// JavaScript 代码 (在古腾堡编辑器中运行)
registerBlockType( 'my-plugin/my-block', {
    title: 'My Block',
    icon: 'smiley',
    category: 'common',
    attributes: {
        title: {
            type: 'string',
            default: '',
        },
        content: {
            type: 'string',
            default: '',
        },
    },
    edit: ( props ) => {
        const { attributes, setAttributes, isSelected } = props;
        const { title, content } = attributes;

        useEffect( () => {
            fetch( wp.rest.api.root + 'my-plugin/v1/my-data' )
                .then( response => response.json() )
                .then( data => {
                    setAttributes( {
                        title: data.title,
                        content: data.content,
                    } );
                } );
        }, [ setAttributes ] ); // useEffect只在setAttributes变化时执行

        return (
            <div>
                <h2>{ title }</h2>
                <p>{ content }</p>
            </div>
        );
    },
    save: ( props ) => {
        const { attributes } = props;
        const { title, content } = attributes;

        return (
            <div>
                <h2>{ title }</h2>
                <p>{ content }</p>
            </div>
        );
    },
} );

在这个例子中，useEffect钩子用于在块加载时调用REST API，并将返回的数据更新到块的属性中。

十、总结：REST API，古腾堡的灵魂伴侣

总而言之，REST API是古腾堡编辑器的灵魂伴侣。它让古腾堡编辑器可以与WordPress后端进行高效的数据交互，从而实现各种强大的功能。理解REST API的工作原理，可以帮助你更好地理解古腾堡编辑器的内部机制，并开发出更加强大的自定义块。

希望今天的课程对你有所帮助。下次再见！