分析 WordPress `rest_url()` 函数源码：如何动态生成 REST API 的端点 URL。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位程序猿、攻城狮，以及未来的代码大师们，大家好！我是你们今天的代码导游，咱们今天聊聊WordPress REST API 的URL是怎么像变魔术一样动态生成的。系好安全带，准备好进入 rest_url() 函数的源码探险之旅吧！

开场白：REST API，URL，以及WordPress的三角恋

首先，咱们得明确三个概念：REST API，URL，WordPress。它们的关系就像三角恋，REST API是主角，URL是联络员，WordPress是舞台。REST API负责提供数据接口，URL负责找到这些接口，WordPress则提供整个运行环境。

简单来说，REST API 就像是餐馆的菜单，URL 就像是菜名，而 WordPress 则是这家餐馆。你想吃什么菜（获取什么数据），就告诉服务员（通过 URL 发送请求），服务员会根据菜单（REST API）给你上菜。

rest_url() 函数，就是那个负责生成“菜名”（URL）的神奇厨师。

rest_url() 函数：URL工厂的秘密

rest_url() 函数是 WordPress 核心函数，位于 wp-includes/functions.php 文件中。它的主要作用就是生成REST API 的端点 URL。

咱们先来看一下它的基本用法：

<?php
$api_url = rest_url( 'wp/v2/posts' );
echo $api_url; // 输出类似于：http://example.com/wp-json/wp/v2/posts
?>

这段代码的作用是生成获取所有文章的 REST API 端点 URL。

但光看用法还不够，咱们得扒开它的源码，看看它到底是怎么运作的。

/**
 * Retrieves the REST URL.
 *
 * @since 4.4.0
 *
 * @param string  $path   Optional. REST route. Default empty.
 * @param string  $scheme Optional. Sanitization scheme. Default 'rest'.
 * @return string REST URL.
 */
function rest_url( $path = '', $scheme = 'rest' ) {
    $rest_prefix = trailingslashit( rest_get_url_prefix() );

    $url = get_url_from_relative( $rest_prefix . ltrim( $path, '/' ), $scheme );

    /**
     * Filters the REST URL.
     *
     * @since 4.4.0
     *
     * @param string $url    REST URL.
     * @param string $path   REST route.
     * @param string $scheme Sanitization scheme.
     */
    return apply_filters( 'rest_url', $url, $path, $scheme );
}

代码不多，但信息量巨大。咱们逐行分析：

$rest_prefix = trailingslashit( rest_get_url_prefix() );
- rest_get_url_prefix()：这个函数负责获取 REST API 的 URL 前缀。默认情况下，这个前缀是 /wp-json。也就是说，所有 REST API 的 URL 都会以 /wp-json 开头。
- trailingslashit()：这个函数的作用是在 URL 前缀后面加上一个斜杠 /，确保 URL 格式正确。
$url = get_url_from_relative( $rest_prefix . ltrim( $path, '/' ), $scheme );
- ltrim( $path, '/' )：这个函数的作用是移除 $path 字符串开头的斜杠 /。
- $rest_prefix . ltrim( $path, '/' )：这里将 REST API 的 URL 前缀和传递进来的 $path 参数拼接起来，形成一个相对 URL。
- get_url_from_relative()：这个函数将相对 URL 转换为绝对 URL，并根据 $scheme 参数进行安全处理。
return apply_filters( 'rest_url', $url, $path, $scheme );
- apply_filters( 'rest_url', $url, $path, $scheme )：这是一个 WordPress 的过滤器钩子，允许开发者通过自定义函数来修改生成的 REST API URL。

rest_get_url_prefix() 函数：URL 前缀的幕后推手

咱们再来看看 rest_get_url_prefix() 函数的源码：

/**
 * Retrieves the REST API URL prefix.
 *
 * @since 4.7.0
 * @since 5.5.0 Added the `$blog_id` parameter.
 *
 * @param int|null $blog_id Optional. Blog ID. Default null.
 * @return string Prefix.
 */
function rest_get_url_prefix( $blog_id = null ) {
    /**
     * Filters the REST API URL prefix.
     *
     * @since 4.4.0
     *
     * @param string $prefix REST API URL prefix.
     */
    return apply_filters( 'rest_url_prefix', 'wp-json' );
}

这个函数也很简单，它只是返回一个字符串 'wp-json'，并通过 apply_filters( 'rest_url_prefix', 'wp-json' ) 提供了一个过滤器钩子，允许开发者修改 REST API 的 URL 前缀。

也就是说，默认情况下，WordPress REST API 的 URL 都会以 /wp-json 开头。但是，开发者可以通过以下代码来修改这个前缀：

<?php
add_filter( 'rest_url_prefix', 'my_custom_rest_url_prefix' );

function my_custom_rest_url_prefix( $prefix ) {
    return 'api';
}

$api_url = rest_url( 'wp/v2/posts' );
echo $api_url; // 输出类似于：http://example.com/api/wp/v2/posts
?>

这段代码将 REST API 的 URL 前缀修改为 /api。

get_url_from_relative() 函数：URL 变形金刚

get_url_from_relative() 函数负责将相对 URL 转换为绝对 URL，并根据 $scheme 参数进行安全处理。由于这个函数涉及到 WordPress URL 的处理机制，比较复杂，咱们就不深入探讨了。

动态生成URL的秘密：参数的灵活运用

rest_url() 函数的强大之处在于它可以动态生成 URL。咱们可以通过传递不同的 $path 参数来生成不同的 REST API 端点 URL。

例如，要获取 ID 为 123 的文章，可以这样写：

<?php
$api_url = rest_url( 'wp/v2/posts/123' );
echo $api_url; // 输出类似于：http://example.com/wp-json/wp/v2/posts/123
?>

要获取所有分类，可以这样写：

<?php
$api_url = rest_url( 'wp/v2/categories' );
echo $api_url; // 输出类似于：http://example.com/wp-json/wp/v2/categories
?>

要获取 ID 为 456 的分类，可以这样写：

<?php
$api_url = rest_url( 'wp/v2/categories/456' );
echo $api_url; // 输出类似于：http://example.com/wp-json/wp/v2/categories/456
?>

$scheme 参数：URL的安全卫士

$scheme 参数用于指定 URL 的安全协议。它可以是以下值之一：

'rest'：默认值，使用 home_url() 函数生成 URL。
'admin'：使用 admin_url() 函数生成 URL。
'https'：强制使用 HTTPS 协议。
'http'：强制使用 HTTP 协议。
'relative'：生成相对 URL。

例如，要强制使用 HTTPS 协议，可以这样写：

<?php
$api_url = rest_url( 'wp/v2/posts', 'https' );
echo $api_url; // 输出类似于：https://example.com/wp-json/wp/v2/posts
?>

总结：rest_url() 函数的价值

rest_url() 函数在 WordPress REST API 中扮演着至关重要的角色。它就像一个 URL 工厂，可以根据不同的参数动态生成各种 REST API 端点 URL。它的价值在于：

简化 URL 生成过程：开发者无需手动拼接 URL，只需调用 rest_url() 函数即可。
提高代码可读性：使用 rest_url() 函数可以使代码更加简洁易懂。
增强 URL 的安全性：rest_url() 函数可以根据 $scheme 参数进行安全处理，确保 URL 的安全性。
提供灵活的扩展性：通过过滤器钩子，开发者可以自定义 REST API 的 URL 前缀，实现更加灵活的 URL 管理。

实战演练：自定义 REST API 端点

咱们来做一个小小的实战演练，创建一个自定义的 REST API 端点，并使用 rest_url() 函数生成该端点的 URL。

首先，咱们需要在 WordPress 中注册一个自定义的 REST API 端点。可以将以下代码添加到主题的 functions.php 文件中：

<?php
add_action( 'rest_api_init', 'register_my_custom_endpoint' );

function register_my_custom_endpoint() {
    register_rest_route(
        'my-namespace/v1',
        '/my-endpoint',
        array(
            'methods'  => 'GET',
            'callback' => 'my_custom_endpoint_callback',
        )
    );
}

function my_custom_endpoint_callback( $request ) {
    return array( 'message' => 'Hello, world!' );
}
?>

这段代码注册了一个名为 /my-namespace/v1/my-endpoint 的 REST API 端点。当访问这个端点时，会返回一个 JSON 对象，其中包含一个 message 属性，值为 'Hello, world!'。

接下来，咱们可以使用 rest_url() 函数生成该端点的 URL：

<?php
$api_url = rest_url( 'my-namespace/v1/my-endpoint' );
echo $api_url; // 输出类似于：http://example.com/wp-json/my-namespace/v1/my-endpoint
?>

通过这个例子，咱们可以看到 rest_url() 函数在自定义 REST API 端点中的应用。

总结与展望

通过今天的源码探险之旅，咱们深入了解了 WordPress rest_url() 函数的内部运作机制。掌握了这个函数，就掌握了动态生成 REST API 端点 URL 的钥匙。希望今天的讲座对大家有所帮助。记住，代码的世界充满乐趣，只要你敢于探索，就能发现无限的可能！

下次有机会，我们再一起探索WordPress的其他神奇函数！祝大家编码愉快！

表格总结

为了方便大家回顾，我把关键点整理成表格：

函数名称	功能描述	关键代码片段	重要参数
`rest_url()`	生成 REST API 端点 URL	`$rest_prefix = trailingslashit( rest_get_url_prefix() );` `$url = get_url_from_relative( $rest_prefix . ltrim( $path, '/' ), $scheme );` `return apply_filters( 'rest_url', $url, $path, $scheme );`	`$path`: REST 路由，例如 `'wp/v2/posts'`。 `$scheme`: URL 协议，例如 `'rest'`，`'https'`，`'http'`。
`rest_get_url_prefix()`	获取 REST API 的 URL 前缀，默认为 `/wp-json`	`return apply_filters( 'rest_url_prefix', 'wp-json' );`	`$blog_id`: 多站点环境下指定博客 ID（可选）。
`apply_filters()`	WordPress 的过滤器钩子，允许开发者自定义函数来修改函数的返回值	`apply_filters( 'rest_url', $url, $path, $scheme );` `apply_filters( 'rest_url_prefix', 'wp-json' );`	第一个参数是过滤器名称，例如 `'rest_url'`，`'rest_url_prefix'`。后续参数是传递给过滤函数的参数。
`register_rest_route()`	注册自定义 REST API 路由	`register_rest_route( 'my-namespace/v1', '/my-endpoint', array( 'methods' => 'GET', 'callback' => 'my_custom_endpoint_callback', ) );`	第一个参数是命名空间，例如 `'my-namespace/v1'`。第二个参数是路由路径，例如 `'/my-endpoint'`。第三个参数是路由选项，包括 `methods`（请求方法）和 `callback`（回调函数）。

希望这个表格能帮助大家更好地理解今天的内容。

发表回复 取消回复

发表回复取消回复