EP076. “给自定义路由加搜索关键词参数（URL parameter + sanitize_text_field）”

首页 › WordPress 开发课程 › REST API 自定义 · EP076

约 7 分钟· #EP076#REST API 自定义

路由目前永远返回全部 professor，这一讲让它能按关键词搜索，比如访问 wp-json/university/v1/search?term=barksalot 只返回名字匹配的那一个 professor。做法是给 WP_Query 加 s（search）参数，同时让回调函数接收 WordPress 传进来的请求参数（URL 上 ?term=xxx 这个 term），并用 sanitize_text_field() 过滤用户输入，防止恶意内容。

涉及文件

wp-content/themes/fictional-university-theme/inc/search-route.php （修改，universitySearchResults() 的参数和 WP_Query 参数）

代码实现

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

// 修改：函数加上 $data 参数，用来接收 URL 上的请求参数（比如 ?term=xxx）
function universitySearchResults($data) {
  $professors = new WP_Query(array(
    'post_type' => 'professor',
    // 新增：s 是 WP_Query 的搜索参数，值来自请求里的 term，并用 sanitize_text_field() 过滤
    's' => sanitize_text_field($data['term'])
  ));

  $professorResults = array();

  while($professors->have_posts()) {
    $professors->the_post();
    array_push($professorResults, array(
      'title' => get_the_title(),
      'permalink' => get_the_permalink()
    ));
  }

  return $professorResults;
}

要点：

register_rest_route() 里指定的回调函数（universitySearchResults）被 WordPress 调用时，会自动带一个参数（这一讲命名为 $data），里面装着这次请求的相关信息，包括 URL 上的查询参数。访问 .../search?term=barksalot 时，$data['term'] 就是 barksalot。这个 term 名字是自己取的，叫 keyword、phrase 都行，只要前端请求和后端读取用同一个名字。
WP_Query 的 s 参数就是「search」，跟内建搜索表单用的是同一个查询参数，直接把想搜的关键词传给它。
安全提示：虽然 WordPress 自身的搜索逻辑已经做了基本的安全处理（不会因为直接搜索就被 SQL 注入打穿），但只要是处理外部用户输入，养成习惯用 sanitize_text_field() 包一层更保险。

[截图：浏览器访问 wp-json/university/v1/search?term=barksalot，查看按关键词过滤后的 JSON 结果]

Hook / Function 速查

名称	类型	用途
`sanitize_text_field($str)`	WP 内建 function（返回值）	过滤掉字符串里的标签、多余空白等，用于清洗用户输入的文本
`$data`（REST 回调函数参数）	WP 传入的请求数据	回调函数只要在参数列表里声明它，就能读到这次请求携带的参数（如 URL 上的 `?term=xxx`）

常见坑

transcript 里提到一个真实踩坑：把 's' => sanitize_text_field($data['term']) 这一行结尾多打了个分号（数组元素之间该用逗号，不是分号；最后一项后面也不需要任何符号），导致请求报错，删掉多余的分号后才恢复正常。

延伸 / 后续讲座会用到

下一讲（EP077）把这个路由从「只查 professor」扩展成同时查 post、page、professor、program、campus、event 六种 post type，并把结果按类型分组返回，为 search overlay 的三栏结果布局做准备。

Sources

Udemy：

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