mcpField
W
wp-rest-api

wp-rest-api

github.com/automattic开发211299 次安装39 周前更新
代码仓库

关于 wp-rest-api

wp-rest-api 是面向 WordPress 开发者的技能，用于构建和排查 REST API 路由。内容涵盖端点设计、验证、权限、身份验证与响应处理。

主要功能

  1. 01创建自定义路由和端点
  2. 02通过 REST 暴露文章类型与分类法
  3. 03验证并清理请求参数
  4. 04配置权限与身份验证
  5. 05处理字段、链接和分页

适用场景

  1. 01构建自定义 WordPress REST 端点
  2. 02排查身份验证或权限错误
  3. 03通过 REST 暴露自定义内容
  4. 04为 API 响应添加经过验证的字段

安装

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

$npx skills add https://github.com/automattic/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 响应添加自定义字段/元数据
  • 通过 REST 暴露自定义文章类型或分类法
  • 实现架构和参数验证
  • 调整响应链接、嵌入内容或分页

所需输入

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

操作步骤

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) 验证/清理请求参数
  • 使用 type、default、required、validate_callback、sanitize_callback 定义 args。
  • 优先使用 JSON Schema 验证：先调用 rest_validate_value_from_schema，再调用 rest_sanitize_value_from_schema。
  • 切勿在端点中直接读取 $_GET/$_POST；请使用 WP_REST_Request。

阅读 references/schema.md。

4) 响应、字段和链接
  • 不要从默认端点中移除核心字段；应添加字段。
  • 对计算字段使用 register_rest_field；对元数据使用带有 show_in_rest 的 register_meta。
  • 对于 object/array 类型的元数据，请在 show_in_rest.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（操作为 wp_rest）。
  • 对于外部客户端：使用应用程序密码（基本身份验证）或身份验证插件。
  • 在 permission_callback 中进行能力检查（授权），而不只是检查“是否已登录”。

阅读 references/authentication.md。

6) 面向客户端的行为（发现、分页、嵌入）
  • 确保能够发现 API（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