阐述 WordPress `register_rest_route()` 函数源码：如何注册自定义 REST API 路由。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众，各位朋友，大家好！我是今天的主讲人，让我们开始今天的“WordPress REST API 自定义路由注册之旅”。今天我们要深入研究WordPress中register_rest_route()这个神秘又强大的函数，看看它如何帮助我们构建自己的REST API乐园。

开场白：为什么我们需要自定义REST API？

想象一下，WordPress就像一个功能强大的瑞士军刀，但有时候，我们需要一把专门定制的螺丝刀来解决特定的问题。WordPress自带的REST API已经很棒了，但它可能无法满足所有需求。这时候，自定义REST API就派上用场了。它可以让我们：

扩展WordPress功能： 例如，创建一个API来处理用户提交的表单，或者与第三方服务集成。
优化数据访问： 根据特定需求定制API返回的数据结构，避免不必要的数据传输。
提高安全性： 通过自定义权限控制，确保只有授权用户才能访问敏感数据。
构建更灵活的应用： 将WordPress作为后端，为移动应用、单页应用等提供数据支持。

register_rest_route()：REST API 路由注册的魔法棒

register_rest_route() 函数是 WordPress 中用于注册自定义 REST API 路由的核心函数。它接受三个主要参数：命名空间、路由和参数数组。让我们逐一拆解：

register_rest_route( string $namespace, string $route, array $args = array() );

$namespace (字符串): 这是一个命名空间，用于区分不同的API。就像你家的地址一样，确保你的API不会和别人的API“撞衫”。通常，我们使用插件或主题的名称作为命名空间，例如 'my-plugin/v1' 或 'my-theme/v2'。使用版本号是个好习惯，方便日后维护升级。
$route (字符串): 这是API的路径，也就是用户访问API时使用的URL。例如 'posts'、'users' 或 'comments'。路由应该以斜杠开头 /。
$args (数组): 这是一个包含各种选项的数组，用于定义API的行为。例如，指定处理请求的回调函数、HTTP方法、权限控制等。这是最重要，也是最灵活的部分。

解剖 $args 参数数组：API 的灵魂

$args 数组是定义API行为的关键。它包含了很多选项，但最常用的包括：

methods (字符串或数组): 指定允许的HTTP方法，例如 'GET'、'POST'、'PUT'、'DELETE'。可以是单个方法字符串，也可以是包含多个方法字符串的数组。
callback (callable): 这是处理API请求的回调函数。当用户访问API路由时，WordPress会调用这个函数来处理请求并返回数据。
permission_callback (callable): 这是权限检查的回调函数。在调用callback之前，WordPress会先调用这个函数来检查用户是否有权限访问API。如果权限检查失败，API会返回一个错误。
args (数组): 定义API接受的参数。可以指定参数的类型、是否必需、默认值等。

实战演练：注册一个简单的 GET API

让我们创建一个简单的API，用于获取当前站点的信息。

add_action( 'rest_api_init', function () {
  register_rest_route( 'my-plugin/v1', '/site-info', array(
    'methods'  => 'GET',
    'callback' => 'my_plugin_get_site_info',
    'permission_callback' => '__return_true', // 允许所有用户访问
  ) );
} );

function my_plugin_get_site_info( WP_REST_Request $request ) {
  $data = array(
    'site_name' => get_bloginfo( 'name' ),
    'site_description' => get_bloginfo( 'description' ),
    'site_url' => get_bloginfo( 'url' ),
  );

  return rest_ensure_response( $data );
}

代码解释：

add_action( 'rest_api_init', function () { ... } );: 我们使用 rest_api_init 钩子来确保在 REST API 初始化后注册路由。这是一个非常重要的步骤，否则你的路由可能无法正常工作。
register_rest_route( 'my-plugin/v1', '/site-info', ... );: 我们注册一个名为 'my-plugin/v1' 的命名空间下的 /site-info 路由。
'methods' => 'GET': 指定只允许 GET 请求访问这个API。
'callback' => 'my_plugin_get_site_info': 指定 my_plugin_get_site_info 函数作为处理请求的回调函数。
'permission_callback' => '__return_true': 使用 __return_true 函数作为权限检查的回调函数，这意味着允许所有用户（包括未登录用户）访问这个API。
my_plugin_get_site_info( WP_REST_Request $request ): 这是处理API请求的回调函数。它接收一个 WP_REST_Request 对象，其中包含请求的所有信息。
$data = array( ... );: 我们创建一个包含站点信息的数组。
return rest_ensure_response( $data );: 使用 rest_ensure_response() 函数将数据转换为 REST API 响应对象。这个函数会自动处理数据序列化和HTTP头设置。

如何测试这个API？

你可以使用任何HTTP客户端（例如Postman、curl）或浏览器来测试这个API。只需访问 你的网站地址/wp-json/my-plugin/v1/site-info 即可。你应该会看到一个包含站点信息的JSON响应。

进阶：处理 POST 请求和参数

让我们创建一个更复杂的API，用于接收用户提交的表单数据。

add_action( 'rest_api_init', function () {
  register_rest_route( 'my-plugin/v1', '/submit-form', array(
    'methods'  => 'POST',
    'callback' => 'my_plugin_submit_form',
    'permission_callback' => '__return_true',
    'args'     => array(
      'name' => array(
        'required' => true,
        'type'     => 'string',
        'description' => '用户的姓名',
      ),
      'email' => array(
        'required' => true,
        'type'     => 'string',
        'format'   => 'email',
        'description' => '用户的邮箱',
      ),
      'message' => array(
        'required' => true,
        'type'     => 'string',
        'description' => '用户的信息',
      ),
    ),
  ) );
} );

function my_plugin_submit_form( WP_REST_Request $request ) {
  $parameters = $request->get_params();

  $name = sanitize_text_field( $parameters['name'] );
  $email = sanitize_email( $parameters['email'] );
  $message = sanitize_textarea_field( $parameters['message'] );

  // 在这里处理表单数据，例如保存到数据库或发送邮件
  $data = array(
    'status' => 'success',
    'message' => '表单提交成功！',
  );

  return rest_ensure_response( $data );
}

代码解释：

'methods' => 'POST': 指定只允许 POST 请求访问这个API。
'args' => array( ... ): 定义API接受的参数。我们定义了三个参数：name、email 和 message。
- 'required' => true: 指定参数是必需的。
- 'type' => 'string': 指定参数的类型是字符串。
- 'format' => 'email': 指定参数的格式是邮箱地址。
- 'description' => '用户的姓名': 提供参数的描述，方便阅读API文档。
$request->get_params(): 从请求中获取所有参数。
sanitize_text_field()、sanitize_email()、sanitize_textarea_field(): 对用户提交的数据进行安全过滤，防止XSS攻击。 永远不要相信用户输入的数据！

如何测试这个API？

你可以使用Postman或其他HTTP客户端发送一个 POST 请求到 你的网站地址/wp-json/my-plugin/v1/submit-form，并在请求体中包含 name、email 和 message 参数。

权限控制：保护你的API

permission_callback 是保护API的关键。我们可以使用它来检查用户是否已登录、是否具有特定角色或权限。

function my_plugin_check_permission() {
  if ( ! is_user_logged_in() ) {
    return new WP_Error( 'rest_not_logged_in', '您必须登录才能访问此API。', array( 'status' => 401 ) );
  }

  return true; // 允许已登录用户访问
}

add_action( 'rest_api_init', function () {
  register_rest_route( 'my-plugin/v1', '/protected-data', array(
    'methods'  => 'GET',
    'callback' => 'my_plugin_get_protected_data',
    'permission_callback' => 'my_plugin_check_permission',
  ) );
} );

function my_plugin_get_protected_data( WP_REST_Request $request ) {
  // 只有登录用户才能访问的代码
  $data = array(
    'secret' => '这是只有登录用户才能看到的数据！',
  );

  return rest_ensure_response( $data );
}

代码解释：

my_plugin_check_permission(): 这是一个权限检查的回调函数。它使用 is_user_logged_in() 函数来检查用户是否已登录。
return new WP_Error( ... ): 如果用户未登录，我们返回一个 WP_Error 对象，其中包含错误代码、错误消息和HTTP状态码。
'permission_callback' => 'my_plugin_check_permission': 指定 my_plugin_check_permission 函数作为权限检查的回调函数。

高级技巧：使用参数进行过滤和分页

我们可以使用API参数来过滤和分页数据。

add_action( 'rest_api_init', function () {
  register_rest_route( 'my-plugin/v1', '/posts', array(
    'methods'  => 'GET',
    'callback' => 'my_plugin_get_posts',
    'permission_callback' => '__return_true',
    'args'     => array(
      'category' => array(
        'type' => 'integer',
        'description' => '分类ID',
      ),
      'per_page' => array(
        'type' => 'integer',
        'default' => 10,
        'description' => '每页文章数量',
      ),
      'page' => array(
        'type' => 'integer',
        'default' => 1,
        'description' => '页码',
      ),
    ),
  ) );
} );

function my_plugin_get_posts( WP_REST_Request $request ) {
  $parameters = $request->get_params();

  $category = isset( $parameters['category'] ) ? intval( $parameters['category'] ) : 0;
  $per_page = intval( $parameters['per_page'] );
  $page = intval( $parameters['page'] );

  $args = array(
    'posts_per_page' => $per_page,
    'paged' => $page,
  );

  if ( $category > 0 ) {
    $args['cat'] = $category;
  }

  $query = new WP_Query( $args );

  $posts = array();
  while ( $query->have_posts() ) {
    $query->the_post();
    $posts[] = array(
      'id' => get_the_ID(),
      'title' => get_the_title(),
      'content' => get_the_content(),
    );
  }

  wp_reset_postdata();

  return rest_ensure_response( $posts );
}

总结：register_rest_route() 的威力

register_rest_route() 函数是构建自定义 WordPress REST API 的基石。通过灵活地使用 $namespace、$route 和 $args 参数，我们可以创建各种各样的API来满足不同的需求。记住，权限控制是至关重要的，要确保你的API是安全的。

一些建议：

保持API简洁易懂： 遵循 RESTful API 设计原则，使用清晰的路由和参数命名。
编写完善的API文档： 方便其他开发者使用你的API。可以使用Swagger等工具自动生成API文档。
进行充分的测试： 确保API在各种情况下都能正常工作。
考虑版本控制： 随着项目的演进，你的API可能会发生变化。使用版本号来管理不同的API版本。

常用参数表格：

参数名	类型	描述
`methods`	string/array	允许的 HTTP 方法 (GET, POST, PUT, DELETE, etc.)。可以是单个字符串，也可以是字符串数组。
`callback`	callable	处理 API 请求的回调函数。
`permission_callback`	callable	权限检查的回调函数。如果权限检查失败，API 会返回一个错误。
`args`	array	定义 API 接受的参数。可以指定参数的类型、是否必需、默认值等。
`schema`	callable	用于描述 API 返回的数据结构的函数。可以用于生成 API 文档。
`update_callback`	callable	用于处理 PUT/POST 请求的回调函数，通常用于更新现有资源。
`create_callback`	callable	用于处理 POST 请求的回调函数，通常用于创建新资源。
`delete_callback`	callable	用于处理 DELETE 请求的回调函数，通常用于删除现有资源。

常用参数类型表格 (在 args 数组中使用):

类型	描述	示例
`string`	字符串类型。	`'type' => 'string'`
`integer`	整数类型。	`'type' => 'integer'`
`number`	数字类型（包括整数和浮点数）。	`'type' => 'number'`
`boolean`	布尔类型 (true 或 false)。	`'type' => 'boolean'`
`array`	数组类型。	`'type' => 'array'`
`object`	对象类型。	`'type' => 'object'`
`null`	空值类型。	`'type' => 'null'`
`email`	字符串类型，且必须是有效的邮箱地址 (通过 `'format' => 'email'` 设置)。	`'type' => 'string', 'format' => 'email'`
`url`	字符串类型，且必须是有效的 URL (通过 `'format' => 'uri'` 设置)。	`'type' => 'string', 'format' => 'uri'`
`date`	字符串类型，且必须是有效的日期 (通过 `'format' => 'date'` 设置)。	`'type' => 'string', 'format' => 'date'`
`date-time`	字符串类型，且必须是有效的日期和时间 (通过 `'format' => 'date-time'` 设置)。	`'type' => 'string', 'format' => 'date-time'`

希望今天的讲解能够帮助大家更好地理解和使用 register_rest_route() 函数，构建出更强大的 WordPress REST API！感谢大家的观看！

发表回复 取消回复

发表回复取消回复