剖析 WordPress `rest_authentication_errors` 钩子源码：如何通过它实现自定义的 REST API 认证逻辑。

各位靓仔靓女，晚上好！我是你们的老朋友，今晚咱们来聊聊 WordPress REST API 认证这块的硬骨头，特别是 rest_authentication_errors 这个钩子，看看它到底能玩出什么花样。

先别慌，我知道 REST API 认证听起来就让人头大，但其实只要掌握了方法，就能像切西瓜一样轻松搞定。今天咱们的目标就是，让你不仅知道 rest_authentication_errors 是什么，还能用它来定制自己的认证逻辑，让你的 API 接口安全又个性。

一、WordPress REST API 认证机制概览

在深入 rest_authentication_errors 之前，咱们先来简单回顾一下 WordPress REST API 的认证流程。

默认情况下，WordPress REST API 提供了几种认证方式：

1. Cookie 认证： 这是最常用的方式，当你登录 WordPress 后台时，浏览器会保存一个 cookie，后续的 API 请求会带上这个 cookie，WordPress 通过验证 cookie 来确认你的身份。这种方式只适用于从 WordPress 站点本身发起的请求，比如主题中的 JavaScript 代码。

2. nonce 认证： nonce（Number used once）是一种安全令牌，用于防止 CSRF（跨站请求伪造）攻击。你可以使用 wp_nonce_field() 函数在表单中生成 nonce，然后通过 API 请求发送 nonce，WordPress 会验证 nonce 的有效性。

3. OAuth 1.0a： 一种比较老的认证协议，现在已经很少使用了。

4. Basic Auth： 简单粗暴，直接在请求头中发送用户名和密码。不安全，强烈不推荐在生产环境中使用。

5. Application Passwords： WordPress 5.6 引入的新功能，允许用户为应用程序创建专用密码，用于 API 认证。

这些默认的认证方式，在很多情况下已经足够使用了。但是，如果你需要更高级、更灵活的认证方式，比如：

• 使用 JWT（JSON Web Token）认证
• 使用第三方 OAuth 2.0 服务认证
• 基于 API 密钥进行认证
• …

这时候，就需要用到 rest_authentication_errors 这个钩子了。

二、rest_authentication_errors 钩子：认证的救星

rest_authentication_errors 钩子允许你在 WordPress REST API 认证过程中的任何时候，介入并修改认证结果。简单来说，你可以用它来：

• 添加自定义的认证逻辑
• 覆盖默认的认证逻辑
• 返回自定义的错误信息

这个钩子会在 rest_authentication() 函数中被触发，这个函数是 WordPress REST API 的认证入口点。

rest_authentication_errors 钩子的原型：

apply_filters( 'rest_authentication_errors', WP_Error|null, WP_REST_Request $request );

• WP_Error|null: 如果认证失败，则返回一个 WP_Error 对象，包含错误代码和错误信息。如果认证成功，则返回 null。
• WP_REST_Request $request: 代表当前的 REST API 请求对象，包含了请求的所有信息，比如请求头、请求参数、请求方法等等。

三、rest_authentication_errors 钩子的使用姿势

说了这么多，不如来点实际的。下面咱们就通过几个例子，来看看 rest_authentication_errors 钩子到底该怎么用。

例1：基于 API 密钥的认证

假设你想实现一种基于 API 密钥的认证方式，用户需要在请求头中包含一个 X-API-Key 字段，只有提供了正确的 API 密钥，才能访问 API 接口。

首先，你需要定义一个 API 密钥，并将其存储在 WordPress 选项中：

function my_plugin_activate() {
  // 生成一个随机的 API 密钥
  $api_key = wp_generate_password( 32, false );
  // 将 API 密钥存储在 WordPress 选项中
  update_option( 'my_plugin_api_key', $api_key );
}
register_activation_hook( __FILE__, 'my_plugin_activate' );

function my_plugin_deactivate() {
  // 删除 API 密钥
  delete_option( 'my_plugin_api_key' );
}
register_deactivation_hook( __FILE__, 'my_plugin_deactivate' );

这段代码在插件激活时生成一个随机的 API 密钥，并将其存储在 my_plugin_api_key 选项中。在插件停用时，删除这个选项。

然后，你需要使用 rest_authentication_errors 钩子来验证 API 密钥：

add_filter( 'rest_authentication_errors', 'my_plugin_rest_api_authentication' );

function my_plugin_rest_api_authentication( $result ) {
  // 如果已经有错误，直接返回
  if ( ! empty( $result ) ) {
    return $result;
  }

  // 获取 API 密钥
  $api_key = get_option( 'my_plugin_api_key' );

  // 从请求头中获取 X-API-Key
  $request_api_key = isset( $_SERVER['HTTP_X_API_KEY'] ) ? $_SERVER['HTTP_X_API_KEY'] : '';

  // 验证 API 密钥
  if ( $request_api_key !== $api_key ) {
    return new WP_Error(
      'rest_api_key_invalid',
      'API 密钥无效',
      array( 'status' => 401 )
    );
  }

  // 认证成功，返回 null
  return $result;
}

这段代码首先检查是否已经有认证错误，如果有，则直接返回。然后，它从 WordPress 选项中获取 API 密钥，并从请求头中获取 X-API-Key 字段的值。如果两个值不相等，则返回一个 WP_Error 对象，表示认证失败。如果认证成功，则返回 null。

例2：基于 JWT (JSON Web Token) 的认证

JWT 是一种流行的认证方式，它使用 JSON 对象来安全地传输信息。

首先，你需要安装一个 JWT 库，比如 Firebase JWT：

composer require firebase/php-jwt

然后，你需要生成一个 JWT：

use FirebaseJWTJWT;

function my_plugin_generate_jwt( $user_id ) {
  $key = 'your-secret-key'; // 你的密钥，一定要保密
  $payload = array(
    'iss' => 'your-site.com', // 你的网站
    'aud' => 'your-site.com', // 你的网站
    'iat' => time(),          // Issued At: 时间戳
    'nbf' => time(),          // Not Before: 时间戳
    'exp' => time() + 60 * 60, // 过期时间：1小时
    'user_id' => $user_id,      // 用户ID
  );

  $jwt = JWT::encode( $payload, $key, 'HS256' );
  return $jwt;
}

这段代码使用 Firebase JWT 库生成一个 JWT，其中包含了用户 ID 和过期时间等信息。

接下来，你需要使用 rest_authentication_errors 钩子来验证 JWT：

add_filter( 'rest_authentication_errors', 'my_plugin_rest_api_jwt_authentication' );

function my_plugin_rest_api_jwt_authentication( $result ) {
  // 如果已经有错误，直接返回
  if ( ! empty( $result ) ) {
    return $result;
  }

  // 从请求头中获取 Authorization
  $auth_header = isset( $_SERVER['HTTP_AUTHORIZATION'] ) ? $_SERVER['HTTP_AUTHORIZATION'] : '';

  // 如果 Authorization 为空，返回错误
  if ( empty( $auth_header ) ) {
    return new WP_Error(
      'rest_jwt_missing',
      '缺少 Authorization 请求头',
      array( 'status' => 401 )
    );
  }

  // 提取 JWT
  $jwt = str_replace( 'Bearer ', '', $auth_header );

  // 验证 JWT
  try {
    $key = 'your-secret-key'; // 你的密钥，一定要保密
    $decoded = JWT::decode( $jwt, $key, array( 'HS256' ) );

    // 获取用户 ID
    $user_id = $decoded->user_id;

    // 验证用户是否存在
    $user = get_user_by( 'ID', $user_id );
    if ( ! $user ) {
      return new WP_Error(
        'rest_jwt_invalid_user',
        '用户不存在',
        array( 'status' => 401 )
      );
    }

    // 设置当前用户
    wp_set_current_user( $user_id );

    // 认证成功，返回 null
    return $result;

  } catch ( Exception $e ) {
    return new WP_Error(
      'rest_jwt_invalid',
      'JWT 无效: ' . $e->getMessage(),
      array( 'status' => 401 )
    );
  }
}

这段代码首先从请求头中获取 Authorization 字段的值，然后提取 JWT。接着，它使用 Firebase JWT 库验证 JWT 的有效性，并获取用户 ID。最后，它验证用户是否存在，并设置当前用户。如果 JWT 无效或用户不存在，则返回一个 WP_Error 对象，表示认证失败。

例3：禁用所有默认认证方式

有时候，你可能需要完全禁用 WordPress 默认的认证方式，只使用你自定义的认证方式。可以使用以下代码：

add_filter( 'rest_authentication_errors', 'my_plugin_disable_default_authentication' );

function my_plugin_disable_default_authentication( $result ) {
  if ( true === $result || is_wp_error( $result ) ) {
    return $result;
  }

  return new WP_Error(
    'rest_no_route',
    'No route was found matching the URL and request method',
    array( 'status' => 401 )
  );
}

这段代码会覆盖默认的认证逻辑，并返回一个 WP_Error 对象，表示没有找到匹配的路由。这样，只有你自定义的认证方式才能通过认证。

四、一些需要注意的点

• 安全第一： 在实现自定义认证逻辑时，一定要注意安全性。比如，API 密钥要使用随机生成的字符串，并存储在安全的地方。JWT 的密钥一定要保密，不要泄露。
• 错误处理： 认证失败时，一定要返回清晰的错误信息，方便客户端调试。
• 性能优化： 认证逻辑不要太复杂，尽量避免不必要的数据库查询和计算。
• 用户体验： 提供友好的认证方式，方便用户使用。
• 优先级问题： 如果多个插件都使用了 rest_authentication_errors 钩子，它们的执行顺序是不确定的。你可以使用 add_filter() 函数的第三个参数来指定优先级，数值越小，优先级越高。

五、代码表格：认证逻辑对比

为了方便大家理解，我把上面三个例子中的认证逻辑整理成一个表格：

认证方式	请求头	验证逻辑	成功后的操作	失败后的操作
API 密钥	X-API-Key	1. 从请求头中获取 X-API-Key 的值。	返回 null，表示认证成功。	返回 WP_Error 对象，包含错误代码 rest_api_key_invalid 和错误信息 "API 密钥无效"。
		2. 从 WordPress 选项中获取 API 密钥。
		3. 比较两个值是否相等。
JWT	Authorization: Bearer <JWT>	1. 从请求头中获取 Authorization 的值。	1. 使用 wp_set_current_user() 函数设置当前用户。	返回 WP_Error 对象，包含错误代码 rest_jwt_missing（缺少请求头）、rest_jwt_invalid（JWT 无效）或 rest_jwt_invalid_user（用户不存在）以及相应的错误信息。
		2. 提取 JWT。	2. 返回 null，表示认证成功。
		3. 使用密钥验证 JWT 的有效性。
		4. 从 JWT 中获取用户 ID。
		5. 验证用户是否存在。
禁用默认认证	无	始终返回 WP_Error 对象，包含错误代码 rest_no_route 和错误信息 "No route was found matching the URL and request method"。	不适用	返回 WP_Error 对象，包含错误代码 rest_no_route 和错误信息 "No route was found matching the URL and request method"。

六、总结

rest_authentication_errors 钩子是 WordPress REST API 认证的利器，它可以让你轻松实现自定义的认证逻辑，满足各种各样的需求。掌握了这个钩子，你就可以为你的 API 接口保驾护航，让你的数据更安全。

好了，今天的讲座就到这里。希望大家能够学有所获，下次有机会再和大家分享更多关于 WordPress 的知识。记得多多实践，才能真正掌握这些技巧。拜拜！