wp-rest-api

WP REST API

适用场景

在以下场景中使用此 Skill：

• 创建或更新 REST 路由/端点
• 排查 401/403/404 报错、权限不足或 nonce 校验失败问题
• 向 REST 响应数据中添加自定义字段/元数据（meta）
• 通过 REST API 暴露自定义文章类型（CPT）或分类法（Taxonomy）
• 实现 Schema 定义与请求参数校验
• 调整响应链接、资源嵌入（embed）或分页逻辑

前置依赖 / 输入信息

• 项目根目录及目标插件/主题/mu-plugin（入口文件路径）。
• 期望的命名空间与版本（例如 my-plugin/v1）及具体路由。
• 身份验证模式（Cookie + nonce、应用密码 Application Passwords 或第三方认证插件）。
• 目标 WordPress 版本约束（若低于 7.0 请明确说明）。

操作流程

0) 诊断并定位 REST API 相关代码

1. 运行项目排查脚本：
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. 检索已有的 REST 代码：
   • register_rest_route
   • WP_REST_Controller
   • rest_api_init
   • show_in_rest, rest_base, rest_controller_class

如果这是全站源码仓库，在修改代码前请先锁定具体的插件或主题目录。

1) 选择合适的实现方案

• 在 wp/v2 中暴露 CPT 或分类法：
  • 必要时设置 show_in_rest => true 及 rest_base。
  • 可选配置 rest_controller_class。
  • 参考 references/custom-content-types.md。
• 自定义端点：
  • 在 rest_api_init 钩子上使用 register_rest_route()。
  • 对于非简单逻辑，优先建议继承控制器类（WP_REST_Controller 子类）。
  • 参考 references/routes-and-endpoints.md 和 references/schema.md。

2) 安全地注册路由（命名空间、请求动作与权限控制）

• 使用独立的命名空间 vendor/v1；除非是 Core 核心功能，否则避免使用 wp/*。
• 必须提供 permission_callback（公开端点可直接使用 __return_true）。
• 建议使用 WP_REST_Server::READABLE/CREATABLE/EDITABLE/DELETABLE 常量定义请求方法。
• 统一通过 rest_ensure_response() 或 WP_REST_Response 返回数据。
• 错误信息统一通过带有明确 status 的 WP_Error 返回。

参考 references/routes-and-endpoints.md。

3) 请求参数校验与清理

• 在 args 中配置 type、default、required、validate_callback 和 sanitize_callback。
• 优先结合 JSON Schema 使用 rest_validate_value_from_schema 进行校验，并用 rest_sanitize_value_from_schema 进行清洗。
• 切勿在端点回调中直接读取 $_GET/$_POST；统一使用 WP_REST_Request 对象。

参考 references/schema.md。

4) 响应格式、扩展字段与关联链接

• 切勿 从默认端点中剔除 Core 核心字段，请通过新增字段的方式扩展。
• 计算属性/动态字段使用 register_rest_field；元数据使用带 show_in_rest 选项的 register_meta。
• 对于 object 或 array 类型的元数据，需在 show_in_rest.schema 中显式定义 Schema。
• 如需获取未过滤的文章内容（例如目录插件注入 HTML 的场景），可传递 ?context=edit 参数以读取 content.raw（需要权限认证）。结合 _fields=content.raw 可有效瘦身响应体积。
• 关联资源链接请使用 WP_REST_Response::add_link() 添加。

参考 references/responses-and-fields.md。

5) 身份验证与授权

• 针对 wp-admin / 前端 JS：使用 Cookie 认证 + X-WP-Nonce 头（action 为 wp_rest）。
• 针对外部客户端：使用应用密码（Application Passwords / Basic Auth）或专用认证插件。
• 在 permission_callback 中做好能力检查（Authorization 授权），不能仅判断是否登录。

参考 references/authentication.md。

6) 客户端交互特性（API 发现、分页与嵌入）

• 确保 API 发现机制正常工作（返回 Link 响应头或 <link rel="https://api.w.org/"> 标签）。
• 支持 _fields、_embed、_method、_envelope 及分页相关的 Header 头。
• 注意 per_page 单页数量上限为 100。

参考 references/discovery-and-params.md。

结果验证

• 请求 /wp-json/ 索引能看到你注册的命名空间。
• 对路由发送 OPTIONS 请求时能够返回 Schema（在配置了 Schema 的前提下）。
• 端点能按预期返回数据；权限不足时能正确返回 401 或 403 状态码。
• show_in_rest 为 true 时，CPT/Taxonomy 路由能正常显示在 wp/v2 下。
• 执行项目的代码检查（lint）、单元测试以及 PHP/JS 构建流程。

常见报错与排查指南

• 404：rest_api_init 钩子未触发、路由拼写错误或未开启固定链接（可通过 ?rest_route= 调试）。
• 401/403：缺失 nonce/认证信息，或 permission_callback 权限要求过于严格。
• 提示缺失 permission_callback 触发 _doing_it_wrong 警告：补上回调函数（公开接口传 __return_true）。
• 参数非法（Invalid params）：args 中的 Schema 定义缺失/错误，或校验回调逻辑有误。
• 字段未返回：show_in_rest 未设为 true、meta 未注册，或 CPT 缺乏 custom-fields 支持。

问题升级 / 进阶参考

如果对于版本兼容性或 API 行为存疑，在自行摸索替代方案前，请优先查阅官方 REST API Handbook 以及 Core 核心文档。