一文搞懂WordPress REST API的使用与自定义接口开发

WordPress REST API 是现代 WordPress 开发的核心基础设施，它让你可以通过 HTTP 请求获取和操作网站数据，无论是构建前后端分离的主题、开发移动端 App，还是实现与第三方系统的数据集成，都离不开它。本文将从基础用法出发，带你掌握自定义 REST API 端点的完整开发流程。

WordPress REST API 基础概览

WordPress 内置的 REST API 遵循 JSON 规范，默认路径前缀为 /wp-json/wp/v2/。常见的内置端点包括：

• /wp-json/wp/v2/posts — 文章列表
• /wp-json/wp/v2/pages — 页面列表
• /wp-json/wp/v2/categories — 分类目录
• /wp-json/wp/v2/users — 用户信息

你可以直接在浏览器中访问 https://yourdomain.com/wp-json/wp/v2/posts?per_page=3 来获取最新的3篇文章，返回格式为标准 JSON 数组。支持 page、per_page、search、orderby 等查询参数进行过滤和分页。

使用 JavaScript 调用 REST API

在前端主题或 Gutenberg 块中，推荐使用 WordPress 内置的 @wordpress/api-fetch 包，它会自动处理 nonce 认证：

import apiFetch from '@wordpress/api-fetch';

// 获取文章列表
apiFetch({ path: '/wp-json/wp/v2/posts?per_page=10' })
  .then((posts) => {
    posts.forEach((post) => {
      console.log(post.title.rendered);
    });
  });

// 创建新文章（需要认证）
apiFetch({
  path: '/wp-json/wp/v2/posts',
  method: 'POST',
  data: {
    title: '通过 REST API 发布的文章',
    content: '这是文章正文内容。',
    status: 'publish',
  },
}).then((newPost) => {
  console.log('文章已创建，ID:', newPost.id);
});

注册自定义 REST API 端点

内置端点无法满足所有业务需求，这时就需要用 register_rest_route() 来注册自定义端点。以下示例在主题的 functions.php 中注册一个获取随机文章的接口：

add_action('rest_api_init', function () {
    register_rest_route('tbr8/v1', '/random-posts', array(
        'methods'  => 'GET',
        'callback' => 'tbr8_get_random_posts',
        'permission_callback' => '__return_true',
        'args' => array(
            'count' => array(
                'default'           => 5,
                'sanitize_callback' => 'absint',
                'validate_callback' => function ($param) {
                    return is_numeric($param) && $param > 0 && $param <= 20;
                },
            ),
        ),
    ));
});

function tbr8_get_random_posts($request) {
    $count = $request->get_param('count');
    $query = new WP_Query(array(
        'post_type'      => 'post',
        'post_status'    => 'publish',
        'orderby'        => 'rand',
        'posts_per_page' => $count,
    ));

    $results = array();
    foreach ($query->posts as $post) {
        $results[] = array(
            'id'        => $post->ID,
            'title'     => get_the_title($post),
            'permalink' => get_permalink($post),
            'thumbnail' => get_the_post_thumbnail_url($post, 'medium'),
        );
    }

    return new WP_REST_Response($results, 200);
}

注册后即可通过 /wp-json/tbr8/v1/random-posts?count=3 调用。注意命名空间 tbr8/v1 避免与核心端点冲突，permission_callback 控制访问权限。

认证与权限控制

写入操作（POST/PUT/DELETE）必须进行身份验证。WordPress 提供多种认证方式：

// 方式1：检查用户权限
function tbr8_create_note($request) {
    if (!current_user_can('edit_posts')) {
        return new WP_Error(
            'forbidden',
            '权限不足',
            array('status' => 403)
        );
    }
    return new WP_REST_Response(array('success' => true), 201);
}

// 方式2：使用 permission_callback
register_rest_route('tbr8/v1', '/notes', array(
    'methods'             => 'POST',
    'callback'            => 'tbr8_create_note',
    'permission_callback' => function () {
        return current_user_can('edit_posts');
    },
));

对于外部客户端调用，推荐使用 Application Passwords（WordPress 5.6+内置）或 JWT 认证插件。Application Passwords 使用方式简单，在用户设置页面生成密码后，用 Basic Auth 方式请求即可。

实战：构建自定义文章类型 API

当你注册了自定义文章类型（CPT），REST API 支持需要手动开启：

register_post_type('product', array(
    'labels' => array('name' => '产品'),
    'public' => true,
    'show_in_rest' => true,       // 关键：开启 REST API 支持
    'rest_base'    => 'products', // 自定义端点路径
    'rest_controller_class' => 'WP_REST_Posts_Controller',
    'supports' => array('title', 'editor', 'thumbnail', 'custom-fields'),
));

// 为自定义字段注册到 REST API
add_action('rest_api_init', function () {
    register_rest_field('product', 'price', array(
        'get_callback' => function ($post) {
            return get_post_meta($post['id'], '_product_price', true);
        },
        'update_callback' => function ($value, $post) {
            update_post_meta($post->ID, '_product_price', sanitize_text_field($value));
        },
        'schema' => array(
            'type'        => 'string',
            'description' => '产品价格',
        ),
    ));
});

这样 /wp-json/wp/v2/products 端点就能返回包含价格字段的产品数据，同时支持通过 API 更新价格。

性能优化与缓存策略

REST API 的性能直接影响前端加载速度，以下是几个关键优化技巧：

// 1. 添加自定义缓存头
add_action('rest_api_init', function () {
    add_filter('rest_post_dispatch', function ($result, $server, $request) {
        if ($request->get_method() === 'GET') {
            $result->header('Cache-Control', 'public, max-age=300');
            $result->header('X-Cache-Hit', 'true');
        }
        return $result;
    }, 10, 3);
});

// 2. 限制返回字段以减小响应体积
add_filter('rest_prepare_post', function ($response, $post) {
    $data = $response->get_data();
    $filtered = array(
        'id'       => $data['id'],
        'title'    => $data['title'],
        'excerpt'  => $data['excerpt'],
        'date'     => $data['date'],
        'link'     => $data['link'],
    );
    $response->set_data($filtered);
    return $response;
}, 10, 3);

此外，可以在 Nginx 层面对 GET 请求设置代理缓存，或使用 Redis 缓存频繁查询的结果，减少数据库压力。

总结

掌握 WordPress REST API 开发的核心要点：

• 内置端点覆盖了文章、页面、用户等常见数据的增删改查
• register_rest_route() 是自定义接口的利器，注意命名空间和权限回调
• 自定义文章类型通过 show_in_rest => true 快速接入 API
• register_rest_field() 可将自定义字段暴露到 API 响应中
• 生产环境务必做好缓存和字段筛选，控制响应体积

合理利用 REST API，可以让 WordPress 从传统 CMS 蜕变为强大的内容服务平台，为多端应用提供统一的数据支撑。