与 WordPress REST API 交互-未完纪

WordPress REST API 常用于读取数据，也支持创建、更新和删除各种 WordPress 数据类型。本课介绍 API schema、请求身份验证、测试工具，以及通过 API 增删改数据的方法。

如果跳过本模块前面的课程，请从 Bookstore 插件仓库 README 的链接下载 1.0.1 版，在本地 WordPress 安装并启用。

课程视频。

REST API schema

使用 API 时，最好随时参考官方 Endpoint Reference，它列出 WordPress 核心提供的全部端点。

点击某个端点，例如 Posts，可以看到 schema，定义读取或创建该类资源时可用的字段。Bookstore 的 books 等自定义文章类型，schema 通常与 posts 相似。

很多字段对应数据库列，但名称有时不同。例如 API 的 title 对应 posts 表的 post_title。必须记住这些差异，并使用 API 所需的正确字段名。

身份验证

REST API 默认使用与 WordPress 后台登录相同的 Cookie 身份验证。非公开、需要登录才能查看或修改的端点，必须携带验证 Cookie，区块编辑器就是这样工作的。

也可以使用 JSON Web Token、OAuth 等方式。WordPress 还内置应用程序密码，按用户创建，让用户访问 API 时无需共享后台登录密码。

在“用户”列表打开用户编辑页，滚动到 Application Passwords，输入名称，点击 Add New Application Password。密码只显示一次，应复制并安全保存；泄露时可在同一页面撤销。

应用程序密码很适合配合 REST 测试工具。若构建移动应用等更复杂集成，原课程建议考虑 JWT 或 OAuth 1.0a。

使用 Postman

可用工具包括 PhpStorm 内置 HTTP 客户端、VS Code 的 Postcode 扩展、Hoppscotch、Postman，以及终端 curl。本课使用 Postman。

从官方网站下载安装后，Postman 默认创建初始工作区，用于保存请求集合。

点击 Create Collection 创建集合，命名后点击 Add a Request。为请求设置名称，输入本地 books 端点，再点击 Send：

https://learn.test/wp-json/wp/v2/books

请求执行后，响应区会解析并展示 JSON。

再创建一个相同 URL 的请求，将方法改为 POST 后发送。POST 表示希望创建或可能更新图书，此时由于未验证身份，会返回错误。

打开 Authorization，选择 Basic Auth，填入用户名和之前创建的应用程序密码，再保存。通过身份验证后，就可以创建图书。

在 Body 选择 raw，再选择 JSON，填入：

{
    "title": "My Postman Book",
    "content": "This is my Postman book",
    "status": "publish"
}

再次发送，图书会创建，并返回新记录 JSON。进入 WordPress 后台查看，应能找到它。

更新图书时，使用相同配置，但在端点 URL 加入图书 ID。删除时同样使用带 ID 的 URL，把方法改为 DELETE，不发送请求体。

删除文章实际是移入回收站，并非永久删除，与后台行为一致。

Postman 既适合学习 API，也能帮助确认发送数据的格式，以及端点是否正确。

创建图书

下面使用 REST API 和 api-fetch 创建图书，需要向 books 端点 POST 标题与正文。

可以在已有图书列表插件基础上继续。先在 bookstore_render_booklist() 管理页回调的已有 HTML 下方，添加输入表单：

<div style="width:50%;">
    <h2>Add Book</h2>
    <form>
        <div>
            <label for="bookstore-book-title">Book Title</label>
            <input type="text" id="bookstore-book-title" placeholder="Title">
        </div>
        <div>
            <label for="bookstore-book-content">Book Content</label>
            <textarea id="bookstore-book-content" cols="100" rows="10"></textarea>
        </div>
        <div>
            <input type="button" id="bookstore-submit-book" value="Add">
        </div>
    </form>
</div>

表单包含标题、正文和提交按钮。

添加按钮点击处理器：

const submitBookButton = document.getElementById( 'bookstore-submit-book' );
if ( submitBookButton ) {
    submitBookButton.addEventListener( 'click', function () {
        // create post code
    } );
}

接下来加入创建图书的逻辑。建议把创建操作放在单独函数，再由点击事件调用。

先创建 submitBook：

function submitBook() {
    // create book code
}

更新事件监听：

submitBookButton.addEventListener( 'click', submitBook );

在函数内读取表单值：

    const title = document.getElementById( 'bookstore-book-title' ).value;
    const content = document.getElementById( 'bookstore-book-content' ).value;

然后使用 api-fetch，指定 books 路径、POST 方法，并将标题和正文作为 data：

    wp.apiFetch( {
        path: '/wp/v2/books/',
        method: 'POST',
        data: {
            title: title,
            content: content
        },
    } ).then( ( result ) => {
        alert( 'Book saved!' );
    } );

打开自定义管理页，输入标题与正文并点击 Add，应看到“Book saved!”提示。再浏览图书列表，就能找到新图书。

更新与删除图书

更新可沿用同一 api-fetch 方式，只需在路径加入目标 ID，并在 data 中传入需要更新的字段值：

    wp.apiFetch( {
        path: '/wp/v2/books/' + id,
        method: 'POST',
        data: {
            title: newTitle,
            content: newContent
        },
    } ).then( ( result ) => {
        alert( 'Book Updated!' );
    } );

删除只需要目标 URL 和 DELETE 方法：

    wp.apiFetch( {
        path: '/wp/v2/books/' + id,
        method: 'DELETE',
    } ).then( ( result ) => {
        alert( 'Book deleted!' );
    } );