mcpField
W
wp-rest-api

wp-rest-api

github.com/wordpress开发2.3k6.0k 次安装1 周前更新
代码仓库

关于 wp-rest-api

面向 WordPress 开发者的 REST API 工作流技能，涵盖路由设计、验证、响应、身份验证与检查。

主要功能

  1. 01路由与端点设计
  2. 02权限与身份验证指导
  3. 03参数架构与验证
  4. 04自定义字段、元数据和链接
  5. 05发现机制与分页检查
  6. 06错误排查与验证

适用场景

  1. 01添加自定义 REST 端点
  2. 02通过 REST 暴露文章类型或分类法
  3. 03排查 REST 权限错误
  4. 04为响应添加经过验证的字段

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wordpress/agent-skills --skill wp-rest-api

安装后在 Claude Code 中输入/wp-rest-api确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
authentication.md
custom-content-types.md
discovery-and-params.md
responses-and-fields.md
routes-and-endpoints.md
schema.md

详细介绍

WP REST API

适用场景

在以下情况下使用此技能：

  • 创建或更新 REST 路由/端点
  • 调试 401/403/404 错误或权限/nonce 问题
  • 向 REST 响应添加自定义字段/meta
  • 通过 REST 暴露自定义文章类型或分类法
  • 实现架构 + 参数验证
  • 调整响应链接/嵌入/分页

所需输入

  • 仓库根目录 + 目标插件/主题/mu-plugin（入口文件的路径）。
  • 预期的命名空间 + 版本（例如 my-plugin/v1）和路由。
  • 身份验证模式（Cookie + nonce、应用程序密码或身份验证插件）。
  • 目标 WordPress 版本限制（低于 7.0 时请注明）。

流程

0) 排查并定位 REST 用法
  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；除非属于核心，否则避免使用 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) 响应、字段和链接
  • 不要从默认端点中移除核心字段；应添加字段。
  • 对于计算字段，使用 register_rest_field；对于 meta，使用带有 show_in_rest 的 register_meta。
  • 对于 object/array 类型的 meta，请在 show_in_rest.schema 中定义架构。
  • 如果需要未经筛选的文章内容（例如，ToC 插件注入 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（操作 wp_rest）。
  • 对于外部客户端：使用应用程序密码（basic auth）或身份验证插件。
  • 在 permission_callback 中进行能力检查（授权），而不只是检查是否“已登录”。

阅读 references/authentication.md。

6) 面向客户端的行为（发现、分页、嵌入）
  • 确保发现机制正常工作（Link 标头或 <link rel="https://api.w.org/">）。
  • 支持 _fields、_embed、_method、_envelope 和分页标头。
  • 请记住，per_page 上限为 100。

阅读 references/discovery-and-params.md。

验证

  • /wp-json/ 索引包含你的命名空间。
  • 对路由发送 OPTIONS 请求时会返回架构（如果已提供）。
  • 端点返回预期数据；权限验证失败时会按预期返回 401/403。
  • 当 show_in_rest 为 true 时，CPT/分类法路由会显示在 wp/v2 下。
  • 运行仓库 lint/测试以及任何 PHP/JS 构建步骤。

故障模式／调试

  • 404：rest_api_init 未触发、路由拼写错误，或固定链接已关闭（使用 ?rest_route=）。
  • 401/403：缺少 nonce／身份验证，或 permission_callback 过于严格。
  • 缺少 permission_callback 时出现 _doing_it_wrong：添加该回调（若为公开接口，可使用 __return_true）。
  • 参数无效：缺少或错误的 args 架构，或验证回调有误。
  • 字段缺失：show_in_rest 为 false、meta 未注册，或 CPT 不支持 custom-fields。

升级处理

如果不确定版本支持情况或行为，请先查阅 REST API Handbook 和核心文档，再考虑采用其他模式。

评论

支持 Markdown