EP074. “从零建一个完全自定义的 REST 路由（register_rest_route）”

上一讲是「改」已有的 REST 输出，这一讲是「建」一个全新的 REST API URL：wp-json/university/v1/search。为什么不直接用内建的 wp/v2/professor?search=xxx 这种 URL？因为：① WordPress 内建搜索只认标题和正文，不认自定义字段和 post 之间的关系（比如 program 关联的 professor），搜「biology」搜不到教生物的教授；② 内建 API 一次只返回一种 post type，search overlay 要同时查 posts/pages/programs/professors/campuses/events 六种类型，就得发六次请求；③ 自建路由可以只返回真正需要的字段（标题、链接），省流量；④ 顺便练手 PHP。这一讲先把路由骨架搭起来，回调函数暂时只返回一句测试文字，验证路由本身能跑通。

涉及文件

• wp-content/themes/fictional-university-theme/functions.php （修改，新增一行 require）
• wp-content/themes/fictional-university-theme/inc/search-route.php （新建）

代码实现

functions.php 顶部新增一行，把新文件 require 进来（保持 functions.php 不至于越写越臃肿）：

<?php

// 新增：引入自定义 REST 路由的独立文件
require get_theme_file_path('/inc/search-route.php');

function university_custom_rest() {
  register_rest_field('post', 'authorName', array(
    'get_callback' => function() {return get_the_author();}
  ));
}

add_action('rest_api_init', 'university_custom_rest');

新建 wp-content/themes/fictional-university-theme/inc/search-route.php：

<?php

add_action('rest_api_init', 'universityRegisterSearch');

function universityRegisterSearch() {
  register_rest_route('university/v1', 'search', array(
    'methods' => WP_REST_SERVER::READABLE,
    'callback' => 'universitySearchResults'
  ));
}

function universitySearchResults() {
  return 'Congratulations, you created a route.';
}

要点：

• register_rest_route($namespace, $route, $args) 三个参数：
  • namespace：自定义 URL 的命名空间，不要用 wp（那是 WordPress 核心专用），这里用 university/v1——带版本号是好习惯，以后要大改 API 就升级成 v2，不会一夜之间破坏别人正在用的旧 URL。
  • route：URL 的最后一段，这里是 search，最终拼出来就是 wp-json/university/v1/search。
  • args 数组：methods 表示这个 URL 响应哪种 HTTP 方法，读取数据用 WP_REST_SERVER::READABLE（等价于 'GET'，但用这个常量在不同主机环境下更保险）；callback 指定处理请求的函数名，这个函数 return 什么，最终就是这个 URL 返回的 JSON。
• 新建的 inc/search-route.php 通过 get_theme_file_path() 拼路径、require 引入，这只是代码组织习惯（避免 functions.php 塞满东西），跟做自定义 REST 路由本身没有必然关系。

[截图：浏览器直接访问 wp-json/university/v1/search，查看返回的测试文字 "Congratulations, you created a route."]

Hook / Function 速查

常见坑

• transcript 里提到，要让自定义 post type（如 professor）出现在内建 REST API 里，只需要在注册该 post type 时加一行 'show_in_rest' => true。不过这个仓库当前的 mu-plugins/university-post-types.php 里 campus、event、program、professor 四个自定义 post type 从这一讲的代码起就已经都是 'show_in_rest' => true，说明这个开关在更早的讲座（注册这些 post type、支持 Gutenberg 编辑器时）就已经打开了，不是这一讲新加的改动——这里只按现有代码如实记录，没有伪造一次「新增」。

延伸 / 后续讲座会用到

下一讲（EP075）让这个路由真正返回有用数据（对 professor 跑 WP_Query），之后 EP076 加搜索关键词参数，EP077 扩展到同时查多种 post type。

Sources

Udemy：

• Become a WordPress Developer: Unlocking Power With Code — Section 15, EP074