剖析 WordPress `rest_get_all_endpoints()` 函数的源码：如何获取所有注册的 REST API 端点。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位API探险家们，欢迎来到今天的“WordPress REST API 端点寻宝记”！我是你们的向导，今天我们将深入WordPress的核心，揭秘rest_get_all_endpoints()这个神奇的函数，看看它是如何像一个雷达一样，扫描出所有注册的REST API端点的。

准备好了吗？让我们开始吧！

一、什么是REST API 端点？（新手扫盲）

在开始之前，先给不熟悉REST API的朋友们简单科普一下。你可以把REST API想象成餐厅的菜单。

餐厅（WordPress）： 提供各种服务（数据）。
菜单（REST API）： 列出可以点的菜（可以请求的数据和操作）。
菜单项（端点）： 具体的一道菜，比如“获取所有文章”（GET /wp/v2/posts）。
你（客户端）： 通过菜单点菜（发送HTTP请求）。
服务员（WordPress服务器）： 根据你的点菜，上菜（返回数据）。

每个“菜单项”（端点）都有一个唯一的地址（URL），客户端通过这个地址来请求特定的数据或执行特定的操作。

二、rest_get_all_endpoints()函数：端点雷达

rest_get_all_endpoints()函数，顾名思义，就是用来获取所有已注册的REST API端点的。它就像一个雷达，扫描整个WordPress系统，把所有可用的端点都找出来。

让我们来看看它的真面目（源码简化版，忽略了一些细节处理）：

<?php
/**
 * Gets all available REST API endpoints.
 *
 * @return array Registered REST API endpoints.
 */
function rest_get_all_endpoints() {
    global $wp_rest_server;

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

    return $wp_rest_server->get_routes();
}

哇！是不是比想象的简单？别被它的简洁外表迷惑了，它背后的机制可不简单。

关键点解析：

global $wp_rest_server;： 这里声明了一个全局变量$wp_rest_server。这个变量非常重要，它是一个WP_REST_Server类的实例，负责处理所有的REST API请求。可以把它看作是REST API总指挥部。
if ( empty( $wp_rest_server ) ) { return array(); }： 这是一个安全检查。如果$wp_rest_server为空（意味着REST API还没有初始化），就返回一个空数组。就像雷达没开机，自然什么也扫描不到。
return $wp_rest_server->get_routes();： 这才是真正的核心！ $wp_rest_server对象调用了get_routes()方法，这个方法会返回一个包含所有已注册端点的数组。

三、WP_REST_Server::get_routes()：端点大本营

WP_REST_Server类的get_routes()方法才是真正存储和管理所有端点信息的地方。我们深入WP_REST_Server类，看看get_routes()方法是如何工作的（同样是简化版）：

<?php
/**
 * Retrieves all registered routes.
 *
 * @return array Registered routes.
 */
public function get_routes() {
    return $this->endpoints;
}

更简单了！ get_routes()方法直接返回了$this->endpoints属性。这个$this->endpoints属性就是一个数组，存储了所有已注册的REST API端点。

关键点解析：

$this->endpoints： 这是WP_REST_Server类的一个私有属性，它是一个关联数组。这个数组的键是端点的URL（比如/wp/v2/posts），值是包含端点详细信息的数组（比如请求方法、回调函数等）。

四、端点是如何注册的？（注册机制揭秘）

既然我们知道了端点存储在哪里，那么问题来了：这些端点是如何被添加到$this->endpoints数组中的呢？

答案是：通过register_rest_route()函数。

<?php
/**
 * Registers a REST route.
 *
 * @param string   $namespace The namespace for the route.
 * @param string   $route     The route to register.
 * @param array    $args      An array of arguments.
 * @param bool     $override  Optional. Whether to override an existing route. Default false.
 * @return bool True if the route was registered successfully, false otherwise.
 */
function register_rest_route( $namespace, $route, $args = array(), $override = false ) {
    global $wp_rest_server;

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

    return $wp_rest_server->register_route( $namespace, $route, $args, $override );
}

可以看到，register_rest_route()函数实际上是调用了WP_REST_Server类的register_route()方法。

让我们来看看WP_REST_Server::register_route()方法（简化版）：

<?php
/**
 * Registers a REST route.
 *
 * @param string   $namespace The namespace for the route.
 * @param string   $route     The route to register.
 * @param array    $args      An array of arguments.
 * @param bool     $override  Optional. Whether to override an existing route. Default false.
 * @return bool True if the route was registered successfully, false otherwise.
 */
public function register_route( $namespace, $route, $args = array(), $override = false ) {
    $route = $this->validate_route( $route );

    if ( ! $route ) {
        return false;
    }

    $full_route = '/' . trim( $namespace, '/' ) . '/' . trim( $route, '/' );

    if ( isset( $this->endpoints[ $full_route ] ) && ! $override ) {
        return false;
    }

    $this->endpoints[ $full_route ] = $args;

    return true;
}

关键点解析：

$full_route = '/' . trim( $namespace, '/' ) . '/' . trim( $route, '/' );： 这里拼接了完整的端点URL。$namespace是命名空间（比如wp/v2），$route是具体的路由（比如posts）。
if ( isset( $this->endpoints[ $full_route ] ) && ! $override ) { return false; }： 检查端点是否已经注册，如果已经注册并且$override参数为false，则返回false，防止重复注册。
$this->endpoints[ $full_route ] = $args;： 将端点信息（$args）添加到$this->endpoints数组中。这就是端点注册的核心步骤！

五、$args参数：端点的详细信息

register_rest_route()函数的$args参数非常重要，它包含了端点的所有详细信息，比如：

methods： 允许的HTTP请求方法（GET、POST、PUT、DELETE等）。
callback： 处理请求的回调函数。
permission_callback： 权限验证的回调函数。
args： 请求参数的定义。

让我们看一个例子：

<?php
register_rest_route( 'my-plugin/v1', '/books', array(
    'methods'  => 'GET',
    'callback' => 'my_plugin_get_books',
    'permission_callback' => '__return_true', // 允许所有人访问
) );

function my_plugin_get_books( $request ) {
    // 从数据库中获取书籍列表
    $books = array(
        array( 'id' => 1, 'title' => 'The Hitchhiker's Guide to the Galaxy' ),
        array( 'id' => 2, 'title' => 'Pride and Prejudice' ),
    );

    return $books;
}

在这个例子中，我们注册了一个名为/my-plugin/v1/books的端点，它只允许GET请求，回调函数是my_plugin_get_books，任何人都可以访问。

六、使用rest_get_all_endpoints()：实战演练

现在我们知道了rest_get_all_endpoints()函数是如何工作的，让我们来实际使用一下：

<?php
$endpoints = rest_get_all_endpoints();

echo '<pre>';
print_r( $endpoints );
echo '</pre>';

这段代码会打印出所有已注册的REST API端点的信息。你会看到一个多维数组，包含了每个端点的URL和详细信息。

七、端点结构分析：深入剖析

rest_get_all_endpoints()返回的数组结构如下（简化版）：

<?php
array(
    '/wp/v2' => array( // 这是一个匹配所有/wp/v2下端点的正则， 不是具体的端点
        array(
            'methods' => WP_REST_Server::READABLE,
            'callback' => 'wp_rest_get_index',
            'permission_callback' => '__return_true',
        ),
    ),
    '/wp/v2/posts' => array(
        array(
            'methods' => WP_REST_Server::READABLE,
            'callback' => array( 'WP_REST_Posts_Controller', 'get_items' ),
            'permission_callback' => array( 'WP_REST_Posts_Controller', 'get_items_permissions_check' ),
            'args' => array(
                'context' => array(
                    'default' => 'view',
                ),
                'page' => array(
                    'default' => 1,
                    'type' => 'integer',
                ),
            ),
        ),
        array(
            'methods' => WP_REST_Server::CREATABLE,
            'callback' => array( 'WP_REST_Posts_Controller', 'create_item' ),
            'permission_callback' => array( 'WP_REST_Posts_Controller', 'create_item_permissions_check' ),
            'args' => array(
                'title' => array(
                    'required' => true,
                    'type' => 'string',
                ),
            ),
        ),
    ),
    '/wp/v2/posts/(?P<id>[d]+)' => array( // 这是一个使用正则表达式匹配的端点
        array(
            'methods' => WP_REST_Server::READABLE,
            'callback' => array( 'WP_REST_Posts_Controller', 'get_item' ),
            'permission_callback' => array( 'WP_REST_Posts_Controller', 'get_item_permissions_check' ),
            'args' => array(
                'context' => array(
                    'default' => 'view',
                ),
            ),
        ),
        array(
            'methods' => WP_REST_Server::EDITABLE,
            'callback' => array( 'WP_REST_Posts_Controller', 'update_item' ),
            'permission_callback' => array( 'WP_REST_Posts_Controller', 'update_item_permissions_check' ),
            'args' => array(
                'title' => array(
                    'type' => 'string',
                ),
            ),
        ),
        array(
            'methods' => WP_REST_Server::DELETABLE,
            'callback' => array( 'WP_REST_Posts_Controller', 'delete_item' ),
            'permission_callback' => array( 'WP_REST_Posts_Controller', 'delete_item_permissions_check' ),
            'args' => array(
                'force' => array(
                    'default' => false,
                    'type' => 'boolean',
                ),
            ),
        ),
    ),
    // ... 更多端点
);

可以看到，每个端点URL对应一个数组，数组中的每个元素都描述了一个特定的请求方法（GET、POST等）和相关的回调函数、权限验证函数和参数定义。

八、实用技巧与注意事项

命名空间的重要性： 使用有意义的命名空间可以避免端点冲突，并且方便管理。
权限验证： 一定要设置合适的权限验证，防止未经授权的访问。
参数验证： 对请求参数进行验证，确保数据的有效性和安全性。
性能优化： 避免在回调函数中执行耗时的操作，可以使用缓存来提高性能。
调试工具： 可以使用REST客户端（比如Postman）来测试你的API端点。

九、高级应用：动态生成API文档

rest_get_all_endpoints()函数的一个高级应用是动态生成API文档。你可以遍历所有端点，提取出URL、请求方法、参数定义等信息，然后生成一个漂亮的API文档，方便开发者使用你的API。

十、总结：REST API 端点寻宝的终点

今天，我们一起探索了rest_get_all_endpoints()函数的奥秘，了解了REST API端点的注册机制和存储结构。希望这次寻宝之旅能让你对WordPress REST API有更深入的理解。

记住，掌握了这些知识，你就可以像一个真正的API探险家一样，自由地探索和利用WordPress REST API的强大功能！

现在，去创造属于你的API世界吧！

发表回复 取消回复

发表回复取消回复