探究 WordPress `rest_authentication_errors` 钩子源码：如何自定义 REST API 的认证逻辑。

各位观众老爷，大家好！ 欢迎来到“WordPress REST API 认证的那些事儿” 讲座现场。今天咱们不讲大道理，就聊点接地气的，如何用 rest_authentication_errors 钩子玩转 WordPress REST API 的认证逻辑，让你的 API 接口更安全，更灵活。

一、 啥是 rest_authentication_errors ？

简单来说，rest_authentication_errors 是 WordPress 提供的一个过滤器钩子，它允许你在 REST API 的认证过程中，添加、修改或移除认证错误。 就像一个关卡，所有未经授权的请求都要经过它，你可以设置各种规则，决定谁能通过，谁会被拦下来。

二、 为啥要自定义认证逻辑？

WordPress 默认提供了一些认证方式，比如 Cookies 认证 (针对已登录用户) 和 OAuth 认证。 但是，在实际应用中，这些可能不够用：

• 特殊用户角色权限: 你可能需要根据用户的特定角色或权限，来决定是否允许访问某个 API 接口。
• 第三方认证: 你可能需要集成第三方认证系统，比如 JWT (JSON Web Token)，来实现跨域认证。
• API 密钥: 你可能需要使用 API 密钥来认证请求，而不是依赖 WordPress 的用户系统。
• 细粒度权限控制: 你可能需要对不同的 API 接口，采用不同的认证方式。

这时，rest_authentication_errors 就派上用场了。 它可以让你根据自己的需求，定制各种认证逻辑。

三、 rest_authentication_errors 的基本用法

使用 rest_authentication_errors 非常简单，只需要把它添加到你的主题或插件的 functions.php 文件中即可。 它的基本结构是这样的：

add_filter( 'rest_authentication_errors', 'my_custom_authentication_errors' );

function my_custom_authentication_errors( $errors ) {
  // 在这里添加你的认证逻辑
  return $errors;
}

• add_filter() 函数： 这是 WordPress 的标准钩子函数，用于将你的自定义函数 my_custom_authentication_errors 挂载到 rest_authentication_errors 钩子上。
• my_custom_authentication_errors() 函数： 这是你的自定义认证函数，它接收一个 $errors 参数，这个参数是一个 WP_Error 对象，包含了现有的认证错误信息。你需要在这个函数中添加你的认证逻辑，并根据认证结果修改 $errors 对象。
• return $errors;： 无论你的认证是否成功，都需要返回 $errors 对象。 如果你的认证成功了，你可以返回 null，表示没有错误。 如果认证失败了，你需要向 $errors 对象添加错误信息。

四、 实战演练：自定义认证逻辑

接下来，我们通过几个实际的例子，来演示如何使用 rest_authentication_errors 实现自定义认证逻辑。

1. 检查 API 密钥

假设我们需要使用 API 密钥来认证请求。 我们可以这样做：

add_filter( 'rest_authentication_errors', 'check_api_key' );

function check_api_key( $errors ) {
  // 检查请求头中是否包含 API 密钥
  $api_key = isset( $_SERVER['HTTP_X_API_KEY'] ) ? $_SERVER['HTTP_X_API_KEY'] : '';

  // 如果没有 API 密钥，返回错误
  if ( empty( $api_key ) ) {
    return new WP_Error(
      'rest_api_key_missing',
      'API 密钥缺失',
      array( 'status' => 401 )
    );
  }

  // 验证 API 密钥是否正确
  $valid_api_key = 'your_secret_api_key'; // 替换成你的实际 API 密钥
  if ( $api_key !== $valid_api_key ) {
    return new WP_Error(
      'rest_api_key_invalid',
      'API 密钥无效',
      array( 'status' => 403 )
    );
  }

  // 如果 API 密钥正确，返回 null，表示没有错误
  return $errors;
}

这段代码做了以下几件事：

• 从请求头中获取 X-API-KEY 的值，作为 API 密钥。
• 如果请求头中没有 X-API-KEY，返回一个 rest_api_key_missing 错误，状态码为 401 (Unauthorized)。
• 如果 API 密钥不正确，返回一个 rest_api_key_invalid 错误，状态码为 403 (Forbidden)。
• 如果 API 密钥正确，返回 $errors，如果 $errors 是一个空对象，相当于返回 null，表示认证成功。

2. 检查用户角色

假设我们需要限制只有管理员才能访问某个 API 接口。 我们可以这样做：

add_filter( 'rest_authentication_errors', 'check_admin_role' );

function check_admin_role( $errors ) {
  // 检查用户是否已登录
  if ( ! is_user_logged_in() ) {
    return new WP_Error(
      'rest_not_logged_in',
      '您尚未登录',
      array( 'status' => 401 )
    );
  }

  // 检查用户是否是管理员
  $user = wp_get_current_user();
  if ( ! in_array( 'administrator', (array) $user->roles ) ) {
    return new WP_Error(
      'rest_not_admin',
      '您不是管理员',
      array( 'status' => 403 )
    );
  }

  // 如果用户是管理员，返回 null，表示没有错误
  return $errors;
}

这段代码做了以下几件事：

• 检查用户是否已登录，如果没有登录，返回一个 rest_not_logged_in 错误，状态码为 401。
• 检查用户是否是管理员，如果不是管理员，返回一个 rest_not_admin 错误，状态码为 403。
• 如果用户是管理员，返回 $errors，如果 $errors 是一个空对象，相当于返回 null，表示认证成功。

3. 集成 JWT 认证

假设我们需要使用 JWT (JSON Web Token) 来认证请求。 我们可以这样做：

add_filter( 'rest_authentication_errors', 'check_jwt_token' );

function check_jwt_token( $errors ) {
  // 引入 JWT 库 (你需要先安装 JWT 库)
  require_once 'vendor/autoload.php'; // 替换成你的 JWT 库的路径

  use FirebaseJWTJWT;
  use FirebaseJWTKey;

  // 检查请求头中是否包含 Authorization Bearer Token
  $auth_header = isset( $_SERVER['HTTP_AUTHORIZATION'] ) ? $_SERVER['HTTP_AUTHORIZATION'] : '';

  // 如果没有 Authorization Bearer Token，返回错误
  if ( empty( $auth_header ) ) {
    return new WP_Error(
      'rest_jwt_missing',
      'JWT Token 缺失',
      array( 'status' => 401 )
    );
  }

  // 从 Authorization Bearer Token 中提取 JWT Token
  $token = str_replace( 'Bearer ', '', $auth_header );

  try {
    // 解码 JWT Token
    $key = 'your_secret_key'; // 替换成你的实际密钥
    $decoded = JWT::decode($token, new Key($key, 'HS256'));

    // 验证 JWT Token 的有效性 (例如，检查过期时间)
    if ( $decoded->exp < time() ) {
      return new WP_Error(
        'rest_jwt_expired',
        'JWT Token 已过期',
        array( 'status' => 403 )
      );
    }

    // 将用户信息存储到 WordPress 的全局变量中，方便后续使用
    $user_id = $decoded->data->user_id;
    wp_set_current_user( $user_id );

  } catch ( Exception $e ) {
    // 如果 JWT Token 无效，返回错误
    return new WP_Error(
      'rest_jwt_invalid',
      'JWT Token 无效: ' . $e->getMessage(),
      array( 'status' => 403 )
    );
  }

  // 如果 JWT Token 有效，返回 null，表示没有错误
  return $errors;
}

这段代码做了以下几件事：

• 引入 JWT 库 (你需要先使用 Composer 安装 JWT 库：composer require firebase/php-jwt)。
• 从请求头中获取 Authorization 的值，并提取 JWT Token (格式为 Bearer <token>)。
• 如果请求头中没有 Authorization，返回一个 rest_jwt_missing 错误，状态码为 401。
• 使用密钥解码 JWT Token。
• 验证 JWT Token 的有效性，例如检查过期时间。
• 如果 JWT Token 无效，返回一个 rest_jwt_invalid 错误，状态码为 403。
• 如果 JWT Token 有效，将用户信息 (例如用户 ID) 存储到 WordPress 的全局变量中，方便后续使用。
• 返回 $errors，如果 $errors 是一个空对象，相当于返回 null，表示认证成功。

五、 错误处理

在自定义认证逻辑时，错误处理非常重要。 你需要向 $errors 对象添加错误信息，并设置相应的状态码。 WordPress REST API 使用标准的 HTTP 状态码来表示错误：

状态码	含义
400	Bad Request (客户端请求有语法错误，不能被服务器所理解)
401	Unauthorized (请求要求身份验证，例如，缺少 API 密钥或 JWT Token)
403	Forbidden (服务器拒绝执行请求，例如，用户没有权限访问该 API 接口)
404	Not Found (服务器找不到请求的资源)
500	Internal Server Error (服务器遇到了一个未知的错误)

六、 多个认证方式

你可以同时使用多个认证方式。 例如，你可以先检查 API 密钥，如果 API 密钥无效，再检查 JWT Token。 这样可以提供更灵活的认证机制。

add_filter( 'rest_authentication_errors', 'my_multiple_authentication' );

function my_multiple_authentication( $errors ) {
  // 检查 API 密钥
  $errors = check_api_key( $errors );

  // 如果 API 密钥无效，检查 JWT Token
  if ( is_wp_error( $errors ) ) {
    $errors = check_jwt_token( $errors );
  }

  // 返回错误
  return $errors;
}

七、 注意事项

• 安全性: 在自定义认证逻辑时，一定要注意安全性。 避免使用弱密码或密钥，并定期更新密钥。
• 性能: 复杂的认证逻辑可能会影响 API 的性能。 尽量优化你的代码，避免不必要的计算。
• 错误提示: 提供清晰的错误提示，帮助开发者调试问题。
• 文档: 编写详细的文档，说明你的 API 的认证方式。

八、 总结

rest_authentication_errors 是一个非常强大的钩子，它可以让你自定义 WordPress REST API 的认证逻辑，实现各种复杂的认证需求。 只要你掌握了它的基本用法，就可以为你的 API 接口提供更安全、更灵活的认证机制。

今天的讲座就到这里，感谢大家的观看！ 希望对大家有所帮助。 如果大家有什么问题，可以在评论区留言，我会尽力解答。

再见！