wp-rest-api-development

WordPress REST API 开发技能

概述

针对 WordPress 插件、主题和自定义代码进行系统化的 REST API 审查。**核心原则：**每个路由都需要明确的契约、显式的授权、经过验证的输入和可预测的输出。审查范围涵盖路由注册、控制器模式、请求解析、架构和参数验证、响应格式、缓存影响及兼容性问题。报告问题时应注明行号和严重性标签，并在有帮助时提供 BAD/GOOD 代码对照。

适用场景

适用于：

• 审查 register_rest_route() 的用法
• 审计自定义 API 端点或控制器类
• 检查 permission_callback 逻辑
• 验证 WP_REST_Request 输入处理
• 审查响应结构、状态码和架构
• 为无头应用或由区块驱动的应用设计版本化端点

不适用于：

• 不涉及 REST 的一般插件架构（请使用 wp-plugin-development）
• 对整个插件进行纯安全审查（请使用 wp-security-review）
• 全面的 WooCommerce 端点审查（仅涉及 WC 时请使用 wp-woocommerce-dev）
• GraphQL 专属指导

代码审查工作流

1. 识别 REST 上下文

   • 插件引导文件中的路由回调
   • 继承 WP_REST_Controller 的控制器类
   • 无头前端集成
   • 仅供内部管理使用的 API

2. 首先检查路由注册

   • 命名空间和版本格式
   • HTTP 方法是否符合操作意图
   • 是否存在明确的 permission_callback
   • 是否通过 args 定义请求验证规则

3. 审查请求处理

   • 使用 $request->get_param() 或带类型的 getter，而不是直接读取全局变量
   • 验证并净化所有用户输入
   • 使用有意义的 WP_Error 拒绝格式错误的输入

4. 审查响应设计

   • 响应结构保持一致
   • 使用恰当的状态码
   • 在适当时使用 rest_ensure_response()
   • 避免泄露内部详情

5. 检查 CRITICAL/WARNING/INFO 模式

   • **CRITICAL：**缺少 permission_callback、写入路由使用 __return_true、直接读取全局变量、未净化的数据库查询
   • **WARNING：**架构不一致、验证薄弱、响应结构混杂、缺少分页信息
   • **INFO：**可考虑使用控制器类、复用架构、整理版本管理

6. 通过交叉引用给出报告

   • 如果身份验证或 nonce 问题占主导地位，请建议使用 /wp-sec-review
   • 如果路由逻辑涉及大量插件架构内容，请建议使用 /wp-plugin-review

特定文件类型检查

路由注册（register_rest_route）

• CRITICAL：缺少 permission_callback
• CRITICAL：写入端点使用 'permission_callback' => '__return_true'
• WARNING：命名空间中没有版本段
• WARNING：在 rest_api_init 之外注册路由
• INFO：重复的内联回调应改用控制器方法

权限回调

• CRITICAL：访问私有数据时缺少能力检查
• WARNING：针对类似管理操作的回调始终返回 true
• WARNING：针对特定用户资源缺少所有权检查
• INFO：可将重复的权限逻辑集中处理

请求参数与验证

• CRITICAL：在端点回调中直接使用 $_GET/$_POST
• WARNING：缺少 sanitize_callback 或 validate_callback
• WARNING：对已知值缺少枚举或格式约束
• INFO：可定义可复用的条目架构

响应处理

• WARNING：不同路由的成功响应结构不一致
• WARNING：在 REST 回调中使用 wp_send_json()，而不是返回响应数据
• INFO：可使用 WP_REST_Response 控制标头和状态码

快速检测搜索模式（API-21）

使用以下 rg 命令快速扫描 REST API，并按严重性分类。

CRITICAL 模式

# register_rest_route candidates
rg -n "register_rest_route\s*\(" . -g '*.php'

# permission_callback returning true
rg -n "permission_callback.*__return_true" . -g '*.php'

# Raw superglobals inside REST callbacks
rg -n "\$_GET|\$_POST|\$_REQUEST" . -g '*.php'

WARNING 模式

# WP_REST_Request usage without obvious validation helpers
rg -n "WP_REST_Request|get_param\s*\(" . -g '*.php'

# REST callbacks using wp_send_json
rg -n "wp_send_json|wp_send_json_success|wp_send_json_error" . -g '*.php'

# Route namespaces to inspect for versioning
rg -n "register_rest_route\s*\(\s*['\"][^'\"]+" . -g '*.php'

INFO 模式

# WP_REST_Controller classes
rg -n "extends\s+WP_REST_Controller" . -g '*.php'

# rest_ensure_response usage
rg -n "rest_ensure_response|new\s+WP_REST_Response" . -g '*.php'

参考文件

• references/route-patterns.md - 路由注册、控制器结构和命名空间设计
• references/schema-and-auth-guide.md - Args 架构、权限回调、输入验证和响应设计

输出格式（API-23）

对于每项发现，请包含：

1. 严重性：CRITICAL、WARNING 或 INFO
2. 文件和行号
3. 问题摘要
4. 该问题对 WordPress REST API 行为的影响
5. 建议的修复方案

如果没有发现问题，请明确说明，并指出任何仍存在的不足，例如缺少测试、架构文档不一致或版本控制策略有限。