FSWP API 开发者
始终应用的基础文档： fswp-developer/references/lean-coding.md（少写、先复用）、fswp-developer/references/coding-standards.md（编码标准、文档、国际化、可访问性），以及 fswp-security-engineer（输入、输出、授权）。
官方参考：REST API 手册（fswp-developer/references/official-docs.md）。fswp-security-engineer 中的安全规则适用于每条路由。
注册路由
function vp_register_routes() {
register_rest_route( 'vendor-prefix/v1', '/items/(?P<id>\d+)', array(
'methods' => WP_REST_Server::READABLE,
'callback' => 'vp_get_item',
'permission_callback' => function ( WP_REST_Request $r ) {
return current_user_can( 'edit_post', (int) $r['id'] );
},
'args' => array(
'id' => array( 'type' => 'integer', 'required' => true, 'sanitize_callback' => 'absint' ),
),
) );
}
add_action( 'rest_api_init', 'vp_register_routes' );
规则
- 命名空间和版本：
vendor-prefix/v1。绝不在核心的wp/v2命名空间中注册。 permission_callback是必需的。 返回一个权限检查，而不仅仅是登录状态。仅对真正公开的数据使用__return_true，并附上注释解释原因。当请求中包含 ID 时，要检查对象级别的访问权限（edit_post、所有权）。- 声明
args，包括type、required、enum、minimum/maximum、validate_callback和sanitize_callback。即使经过验证，请求也是不可信的；使用$request->get_param()的值作为类型后的值。 - 使用
rest_ensure_response()返回数据；错误使用new WP_Error( 'vp_code', __( 'Message', 'text-domain' ), array( 'status' => 404 ) )。使用准确的状态码（400 无效、401 未认证、403 禁止、404 未找到、409 冲突、413 过大）。 - Schema： 实现
get_item_schema()（或schema回调），以便客户端和索引可以描述资源；使用prepare_item_for_response()构建响应。 - 集合： 支持带有硬上限的
page/per_page，设置X-WP-Total和X-WP-TotalPages，绝不返回无边界列表。 - 绝不返回 机密信息、密码哈希、原始选项或其他用户的私有数据。
- 控制器： 对于超过几个路由的情况，扩展
WP_REST_Controller（register_routes、get_items、get_item、create_item、每种方法的权限检查）并只注册一次该类。 - 暴露核心对象： 自定义文章类型和分类法使用
'show_in_rest' => true（和rest_base）；元数据使用register_meta()/register_post_meta()和'show_in_rest' => true，同时提供 schema 和auth_callback。 - 缓存与性能： 廉价的
GET处理器；缓存昂贵的结果（fswp-performance-engineer）；避免在循环中进行查询。
认证
| 客户端 | 方法 |
|---|---|
| 同站点 JS（后台、区块、前端） | Cookie 认证，附带上 X-WP-Nonce 头（wp_create_nonce( 'wp_rest' )，或自动添加的 wp_localize_script / @wordpress/api-fetch） |
| 外部服务器或应用 | 通过 HTTPS 使用应用密码，或经过审查的 OAuth 插件 |
| 公开读取 | 无需认证，仅当数据公开时 |
Nonce 不能替代权限检查。CORS：不要在已认证的路由上开放 Access-Control-Allow-Origin: *。
客户端
在区块和管理界面中使用 @wordpress/api-fetch。通过 code 和 message 处理错误，而不是通过解析文本。
Abilities API
这是一个用于注册离散的、机器可读能力的核心 API（名称、输入 schema、输出 schema、权限检查、执行回调），工具和 AI 代理可以发现并调用它们。这是较新的 API：在使用之前，请确认最低 WordPress 版本和确切的函数名（搜索“Abilities API”）。仅在 PRD 需要代理可调用函数时使用；普通的客户端-服务器调用适用普通 REST。
注册能力时：
- 首先在文档化的钩子上注册类别，然后注册能力。
- 为其提供输入和输出的 JSON Schema，以及一个检查真实能力的
permission_callback。 - 诚实设置安全注解：只读能力不得写入，破坏性能力必须标记。一个写入数据但标记为只读的回调是缺陷，
fswp-reviewer会将其视为缺陷。 - 只将应该远程调用的内容通过 REST 暴露出来。
审计和验证流程：references/abilities.md。
为了提议哪些现有端点应该成为能力，列出每个路由及其方法、当前权限检查、副作用和建议的注解；在获得批准之前不注册任何内容。