发布于 由admin

解析 WordPress `is_rest_api_request()` 函数源码：如何判断当前请求是否为 REST API。

各位观众老爷，大家好！我是你们的老朋友，今天咱们来聊聊 WordPress 里一个很有意思的函数：is_rest_api_request()。这玩意儿就像个侦探，专门负责判断当前请求是不是冲着 REST API 来的。

咱们今天就来剥开它的源码，看看它到底是怎么工作的，顺便也跟大家分享一些使用技巧和注意事项。保证让大家看完之后，以后再遇到 API 请求的问题，心里都有数。

1. 啥是 REST API 请求？

在深入源码之前，咱们先来搞清楚什么是 REST API 请求。简单来说，REST (Representational State Transfer) 是一种软件架构风格，它定义了一组规则，用于创建可扩展的网络服务。WordPress REST API 允许开发者通过 HTTP 请求 (GET, POST, PUT, DELETE 等) 来访问和操作 WordPress 的数据，比如文章、页面、用户等等。

举个例子，你可以用 REST API 来创建一个新的文章，或者获取某个分类下的所有文章。这对于构建移动应用、单页面应用（SPA）或者与其他系统集成非常有用。

2. is_rest_api_request() 的作用

is_rest_api_request() 函数的作用就是判断当前请求是否是针对 WordPress REST API 的。如果返回 true，说明是 API 请求；如果返回 false，说明不是。这个函数在很多场景下都很有用，比如：

  • 自定义 API 行为: 你可以根据是否是 API 请求来执行不同的代码逻辑。
  • 安全验证: 你可以只对 API 请求进行特定的安全验证。
  • 性能优化: 你可以针对 API 请求进行缓存或其他优化。
  • 插件开发: 你可以根据是否是 API 请求来加载不同的插件模块。

3. 源码剖析：一层一层扒开它的心

好了，废话不多说，咱们直接上代码。is_rest_api_request() 函数的源码位于 wp-includes/functions.php 文件中（具体位置可能因 WordPress 版本而异，但通常都在 wp-includes 目录下）。

/**
 * Determines whether the current request is a WP REST API request.
 *
 * @since 4.4.0
 *
 * @global WP_REST_Server $wp_rest_server REST server instance.
 *
 * @return bool True if it's a WP REST API request, false otherwise.
 */
function is_rest_api_request() {
    global $wp_rest_server;

    if ( empty( $wp_rest_server ) ) {
        return false;
    }

    $rest_prefix = trailingslashit( rest_get_url_prefix() );

    /*
     * The WP::parse_request() method will strip the rest_prefix from the
     * beginning of the path.
     *
     * See WP::handle_request() in wp-includes/class-wp.php
     */
    $path = isset( $_SERVER['REQUEST_URI'] ) ? $_SERVER['REQUEST_URI'] : '';

    if ( empty( $path ) ) {
        return false;
    }

    $path = ltrim( $path, '/' );

    $matches = [];
    // See https://www.php.net/manual/en/function.preg-match.php
    // PREG_OFFSET_CAPTURE - If this flag is passed, for every occurring match the appendant string offset will also be returned. Note that this changes the return value in an array where every element matched is an array consisting of the matched string at offset 0 and its string offset into subject at offset 1.
    if ( preg_match( '#^' . $rest_prefix . '#i', $path, $matches ) ) {
        return true;
    }

    return false;
}

/**
 * Retrieves the REST API URL prefix.
 *
 * @since 4.4.0
 *
 * @return string The REST API URL prefix.
 */
function rest_get_url_prefix() {
    /**
     * Filters the REST API URL prefix.
     *
     * @since 4.4.0
     *
     * @param string $prefix URL prefix used for routing REST API requests.
     */
    return apply_filters( 'rest_url_prefix', 'wp-json' );
}

咱们一行一行地分析：

  1. global $wp_rest_server;: 首先，它声明了一个全局变量 $wp_rest_server。这个变量是 WP_REST_Server 类的实例，负责处理 REST API 请求。如果这个变量是空的，说明 REST API 还没被初始化，那肯定不是 API 请求，直接返回 false。

    if ( empty( $wp_rest_server ) ) {
    return false;
}

  2. $rest_prefix = trailingslashit( rest_get_url_prefix() );: 接下来，它获取 REST API 的 URL 前缀，并添加一个斜杠。rest_get_url_prefix() 函数默认返回 'wp-json'，你可以通过 rest_url_prefix 过滤器来修改它。trailingslashit() 函数确保前缀以斜杠结尾，例如 'wp-json/'。

    $rest_prefix = trailingslashit( rest_get_url_prefix() );

    rest_get_url_prefix() 函数本身的代码如下：

    function rest_get_url_prefix() {
    /**
     * Filters the REST API URL prefix.
     *
     * @since 4.4.0
     *
     * @param string $prefix URL prefix used for routing REST API requests.
     */
    return apply_filters( 'rest_url_prefix', 'wp-json' );
}

    可以看到，它只是简单地返回 'wp-json'，并且提供了一个过滤器，允许你自定义前缀。

  3. $path = isset( $_SERVER['REQUEST_URI'] ) ? $_SERVER['REQUEST_URI'] : '';: 然后，它获取请求的 URI (Uniform Resource Identifier)。 $_SERVER['REQUEST_URI'] 包含了请求的完整 URI，例如 '/wp-json/wp/v2/posts'。如果 $_SERVER['REQUEST_URI'] 不存在，则将 $path 设为空字符串。

    $path = isset( $_SERVER['REQUEST_URI'] ) ? $_SERVER['REQUEST_URI'] : '';

  4. if ( empty( $path ) ) { return false; }: 如果请求 URI 为空，则返回 false。

     if ( empty( $path ) ) {
        return false;
    }

  5. $path = ltrim( $path, '/' );: 移除 URI 开头的斜杠。

    $path = ltrim( $path, '/' );

  6. if ( preg_match( '#^' . $rest_prefix . '#i', $path, $matches ) ) { return true; }: 这是最关键的一步。它使用正则表达式来判断请求的 URI 是否以 REST API 前缀开头。preg_match() 函数会检查 $path 是否匹配模式 '#^' . $rest_prefix . '#i'。

    • # 是正则表达式的分隔符。
    • ^ 表示字符串的开头。
    • . 是一个特殊字符，需要转义，所以写成 .。
    • i 表示忽略大小写。
    • $matches 是一个数组，用于存储匹配的结果。

    如果匹配成功，说明请求的 URI 以 REST API 前缀开头，函数返回 true。

    $matches = [];
if ( preg_match( '#^' . $rest_prefix . '#i', $path, $matches ) ) {
    return true;
}

  7. return false;: 如果以上所有步骤都没有返回 true，说明不是 REST API 请求，函数返回 false。

    return false;

总结一下:

is_rest_api_request() 函数的工作流程如下：

步骤 描述
1 检查 $wp_rest_server 是否已初始化。
2 获取 REST API 的 URL 前缀。
3 获取请求的 URI。
4 使用正则表达式判断 URI 是否以 REST API 前缀开头。
5 返回判断结果。

4. 使用场景举例：在你的代码中用起来

现在咱们知道了 is_rest_api_request() 函数是怎么工作的，接下来咱们来看看在实际开发中怎么使用它。

例子 1: 自定义 API 响应

假设你想在 API 请求时返回 JSON 格式的数据，而在普通请求时返回 HTML 格式的数据。你可以这样做：

add_action( 'template_redirect', 'my_custom_response' );

function my_custom_response() {
    if ( is_rest_api_request() ) {
        // API 请求
        header( 'Content-Type: application/json' );
        $data = array( 'message' => 'Hello from REST API!' );
        echo json_encode( $data );
        exit;
    } else {
        // 普通请求
        echo '<h1>Hello from the regular website!</h1>';
    }
}

在这个例子中，template_redirect action 会在 WordPress 加载模板之前被触发。my_custom_response() 函数会检查当前请求是否是 API 请求。如果是，它会设置 Content-Type 为 application/json，然后输出 JSON 格式的数据。如果不是，它会输出 HTML 格式的数据。

例子 2: 只对 API 请求进行身份验证

有时候，你可能只想对 API 请求进行身份验证，而允许普通用户直接访问网站。你可以这样做：

add_action( 'template_redirect', 'my_api_authentication' );

function my_api_authentication() {
    if ( is_rest_api_request() ) {
        // API 请求，进行身份验证
        if ( ! is_user_logged_in() ) {
            wp_die( 'Authentication required.', 'Authentication', array( 'response' => 401 ) );
        }
    }
}

在这个例子中，my_api_authentication() 函数会检查当前请求是否是 API 请求。如果是，它会检查用户是否已经登录。如果用户没有登录，它会使用 wp_die() 函数显示一个错误信息，并返回 401 状态码。

例子 3: 根据是否是 API 请求加载不同的插件模块

在插件开发中，你可能需要根据是否是 API 请求来加载不同的模块。你可以这样做：

add_action( 'plugins_loaded', 'my_plugin_load_modules' );

function my_plugin_load_modules() {
    if ( is_rest_api_request() ) {
        // API 请求，加载 API 模块
        require_once plugin_dir_path( __FILE__ ) . 'includes/api-module.php';
    } else {
        // 普通请求，加载普通模块
        require_once plugin_dir_path( __FILE__ ) . 'includes/regular-module.php';
    }
}

在这个例子中，my_plugin_load_modules() 函数会检查当前请求是否是 API 请求。如果是，它会加载 api-module.php 文件。如果不是，它会加载 regular-module.php 文件。

5. 注意事项：别踩坑里了

在使用 is_rest_api_request() 函数时，需要注意以下几点：

  • 确保 REST API 已启用: 如果 REST API 没有启用，is_rest_api_request() 函数始终会返回 false。你可以通过 add_filter( 'rest_authentication_errors', 'my_rest_authentication_errors' ); 来检查 REST API 是否正常工作。

  • 考虑缓存: 如果你的网站使用了缓存插件，可能会导致 $_SERVER['REQUEST_URI'] 的值不正确，从而影响 is_rest_api_request() 函数的判断结果。你需要确保缓存插件能够正确处理 REST API 请求。

  • 自定义 REST API 前缀: 如果你修改了 REST API 的 URL 前缀，你需要相应地修改你的代码，确保 is_rest_api_request() 函数能够正确判断 API 请求。 可以通过 add_filter( 'rest_url_prefix', 'my_custom_rest_prefix' ); 来修改。

  • 别滥用: 虽然 is_rest_api_request() 函数很有用，但是不要滥用它。只在确实需要区分 API 请求和普通请求的场景下才使用它。过度使用可能会导致代码变得复杂难以维护。

6. 总结：侦探的秘密武器

is_rest_api_request() 函数是 WordPress 提供的一个非常实用的工具，它可以帮助你判断当前请求是否是针对 REST API 的。通过理解它的源码和使用场景，你可以在你的代码中灵活地处理 API 请求，从而构建更强大的 WordPress 应用。

希望今天的分享能够帮助大家更好地理解 is_rest_api_request() 函数。 记住，它就像一个侦探，能帮你识别出 REST API 的请求，让你的代码更加智能！

好了，今天的讲座就到这里，希望大家喜欢！咱们下次再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注