mcpField
W
wp-rest-api

wp-rest-api

github.com/firecrawl开发544 次安装38 周前更新
代码仓库

关于 wp-rest-api

为 WordPress 开发者提供 REST API 实现指导，涵盖自定义路由、内容类型、权限、验证与响应处理，并包含排错和验证步骤。

主要功能

  1. 01注册安全的 REST 路由
  2. 02配置内容类型与分类法
  3. 03验证和清理请求参数
  4. 04扩展字段、元数据与链接
  5. 05排查认证及权限错误

适用场景

  1. 01为插件或主题添加自定义端点
  2. 02向 REST 响应公开自定义内容类型
  3. 03诊断 401、403 或 404 错误

安装

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

$npx skills add https://github.com/firecrawl/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