权限配置:WordPress 7.2 Abilities API 权限、输入验证与 JSON 输出指南

本文来源:权限配置:WordPress 7.2 Abilities API 权限、输入验证与 JSON 输出指南 https://gplwp.eastfu.com/wordpress72-geng-xin-abilitiesapi-tong-yi-quan-xian-jian/

WordPress 7.2 更新了 Abilities API,使权限、输入处理和 JSON 输出更加可预测。Abilities 可以声明每次调用都需要的能力。直接通过 PHP 调用和发送 REST 请求时,会根据能力的模式清理输入,而 JSON 结果会保留模式所声明的对象或数组结构。下面的示例说明了能力作者和集成开发者需要更改的内容。

目录 隐藏

声明必需的能力

按能力筛选发现结果

在不同执行路径中一致地准备输入

数字输入会转换为浮点数

清理失败会中止执行

直接权限检查需要已准备的输入

[在 JSON 中保留空对象](#在 JSON 中保留空对象)

集成开发者应做的更改

更新集成

核心答案

常见问题

[WordPress 7.2 中 required_capabilities 与 permission_callback 应如何使用?](#WordPress 7.2 中 required_capabilities 与 permission_callback 应如何使用?)

[为什么 WordPress 7.2 的 number 模式会把整数 10 转成 10.0?](#为什么 WordPress 7.2 的 number 模式会把整数 10 转成 10.0?)

[调用 check_permissions() 前为什么必须先执行 prepare_input()?](#调用 check_permissions() 前为什么必须先执行 prepare_input()?)

声明必需的能力

新的 required_capabilities 注册参数接受一组非空的能力字符串。在检查权限时,WordPress 会使用 current_user_can() 检查每项能力。所有列出的能力都必须通过检查,权限回调才会运行。

对于适用于每次调用的要求,请使用此列表。例如,core/settings-get 始终需要 manage_options。其注册信息声明了该能力,并省略 permission_callback。下面的摘录展示了它的权限参数:

bash 复制代码
array(
    'required_capabilities' => array( 'manage_options' ),
    // No permission_callback: the capability covers every call.
);

如果权限还取决于输入,请将该检查保留在 permission_callback 中。以下能力每次调用都需要 edit_posts,然后检查用户能否编辑所请求的文章。该示例假设 my-plugin 类别已经注册:

bash 复制代码
add_action(
    'wp_abilities_api_init',
    static function () {
        wp_register_ability(
            'my-plugin/get-post-title',
            array(
                'label'                 => __( 'Get post title', 'my-plugin' ),
                'description'           => __( 'Read the title of a post you can edit.', 'my-plugin' ),
                'category'              => 'my-plugin',
                'required_capabilities' => array( 'edit_posts' ),
                'input_schema'          => array(
                    'type'    => 'integer',
                    'minimum' => 1,
                ),
                'output_schema'         => array( 'type' => 'string' ),
                'permission_callback'   => static function ( int $post_id ): bool {
                    return current_user_can( 'edit_post', $post_id );
                },
                'execute_callback'      => static function ( int $post_id ): string {
                    return get_post_field( 'post_title', $post_id, 'raw' );
                },
                'meta'                  => array(
                    'show_in_rest' => true,
                    'annotations' => array( 'readonly' => true ),
                ),
            )
        );
    }
);

请根据能力的要求选择权限参数:

  • 如果非空的 required_capabilities 列表涵盖所有权限检查,请省略 permission_callback。不需要 __return_true。
  • 如果调用需要额外检查(例如访问特定文章),请提供回调。声明的能力会先被检查。
  • 如果 required_capabilities 为空或被省略,则必须提供有效的 permission_callback。仅当该能力有意允许所有人执行时,才使用 __return_true;否则,请提供适当的权限检查。

现有的 wp_ability_permission_result 过滤器仍会接收结果,并可以覆盖该结果,包括因缺少某项能力而导致的拒绝。

按能力筛选发现结果

集成可以通过 $ability->get_required_capabilities() 读取声明信息。该信息也会包含在 REST 发现响应中。

如需请求当前用户满足其声明要求的 Abilities:

bash 复制代码
$abilities = wp_get_abilities(
    array( 'has_required_capabilities' => true )
);

REST 集合支持相同的可选筛选器:

bash 复制代码
GET /wp-json/wp-abilities/v1/abilities?has_required_capabilities=true

此筛选器不会运行权限回调或 wp_ability_permission_result 过滤器。未声明能力的 Abilities 会通过此筛选器(其他发现筛选器仍可能将其排除),而通过发现的 Ability 在处理特定输入时仍可能拒绝执行。在上面的示例中,作者可能会发现该 Ability,却无权通过它读取另一位作者的草稿。

仅声明每次调用都需要的能力。将特定输入的要求放入静态列表,可能会使有权使用其他输入执行该能力的用户无法发现它。

相关工单:#66325。

在不同执行路径中一致地准备输入

WP_Ability::prepare_input() 现在负责处理 execute() 所使用的输入准备工作:

  1. 规范化输入,包括在输入为 null 时应用顶层模式默认值。
  2. 根据输入模式对其进行验证。
  3. 使用该模式对验证后的值进行清理。

权限回调和执行回调会收到准备后的值。在上面的示例中,$ability->execute( '123' ) 会将整数 123 传递给两个回调。模式格式也很重要:使用 format: text-field 声明的字符串会在清理期间去除其标签。

验证在清理之前运行。无效值会在类型转换或属性移除掩盖错误之前被拒绝。准备过程中发生失败会返回 WP_Error 并停止执行。

REST 执行控制器会分别准备原始请求输入,用于权限检查和执行。调用 execute() 的自定义集成可以传入原始输入,让能力(ability)负责准备。

数字输入会转换为浮点数

在直接 PHP 调用中,number 模式会将 10 这样的整数转换为浮点数 10.0,与 REST 行为一致。当回调需要整数时,请使用 integer 模式。使用 number 的回调应接受浮点数,并避免进行 is_int( $input ) 或 $input === 10 之类的检查。

其他模式转换包括:字符串 "false" 转换为布尔值 false,以及在整数数组模式下 "1,2" 转换为 array( 1, 2 )。

清理失败会中止执行

输入可能通过验证但仍会清理失败。例如,array( '1', '01' ) 包含不同的字符串,但两者都会转换为整数 1。这会触发整数数组模式的 uniqueItems: true 错误。

在 7.2 中,此失败会返回 ability_invalid_input,即使发生在嵌套字段中,也会在权限或执行回调运行之前返回。REST 端点返回 HTTP 400。当某个字段失败时,不再回退到未经清理的原始输入;否则,这种回退可能会让权限回调收到字符串 "false",而该字符串在 PHP 中为真值。

直接权限检查需要已准备的输入

check_permissions() 不会准备其输入。如果集成直接调用它,必须先调用 prepare_input(),并在出现错误时停止:

bash 复制代码
$ability = wp_get_ability( 'my-plugin/get-post-title' );

if ( null === $ability ) {
    return new WP_Error( 'example_missing_ability', 'The ability is not registered.' );
}

$input = $ability->prepare_input( '123' );

if ( is_wp_error( $input ) ) {
    return $input;
}

// $input is now the integer 123.
$permission = $ability->check_permissions( $input );

if ( is_wp_error( $permission ) ) {
    return $permission;
}

if ( true !== $permission ) {
    return new WP_Error( 'example_forbidden', 'You cannot edit this post.' );
}

// This checks permission only. To run the ability, use execute().

直接权限检查不会执行能力。要执行,请调用 execute();它会在正常生命周期中执行准备和权限检查。

仅调用 normalize_input() 并不足够:它不包含模式验证和清理。同样,validate_input() 返回的是验证结果,而不是已准备的值。

如果自定义权限检查路径已经对输入进行了规范化和验证,可以用 prepare_input() 替代这些步骤。请在调用 check_permissions() 前保留错误检查:

bash 复制代码
- $input = $ability->normalize_input( $raw_input );
+ $input = $ability->prepare_input( $raw_input );
  if ( is_wp_error( $input ) ) {
      return $input;
  }

- $valid = $ability->validate_input( $input );
- if ( is_wp_error( $valid ) ) {
-     return $valid;
- }

  $permission = $ability->check_permissions( $input );

这会为自定义路径添加模式清理。请继续按照上述方式处理权限结果。

REST 控制器的 sanitize_input_for_ability() 方法在 7.2 中已弃用,并且不再注册为输入清理器。其兼容实现会原样返回输入。

相关工单:#66383。

在 JSON 中保留空对象

即使模式描述的是对象,空 PHP 数组也会编码为 []。这可能导致期望对象的客户端收到数组。

共享的 wp_prepare_json_schema_for_client() 函数可准备模式,以便在 WordPress 服务端验证之外使用。它会移除不支持的关键字,并准备嵌套模式及其现有默认值,因此适用于插件向 REST 客户端或前端公开模式的场景。在 7.2 中,其默认值处理会根据模式保留空对象:

bash 复制代码
$schema = array(
    'type'    => 'object',
    'default' => array(),
);

echo wp_json_encode( wp_prepare_json_schema_for_client( $schema ) );
// {"type":"object","default":{}}

新的 wp_prepare_json_value_for_client() 函数会将相同的区分应用于结果值,包括嵌套属性和数组项:

bash 复制代码
$schema = array(
    'type'       => 'object',
    'properties' => array(
        'settings' => array( 'type' => 'object' ),
        'items'    => array(
            'type'  => 'array',
            'items' => array( 'type' => 'object' ),
        ),
    ),
);

$result = array(
    'settings' => array(),
    'items'    => array( array() ),
);

echo wp_json_encode( wp_prepare_json_value_for_client( $result, $schema ) );
// {"settings":{},"items":[{}]}

Abilities REST API 在准备模式和执行结果时会应用这些辅助函数,包括根级空对象和顶层列表中的对象。WordPress AI Client 也会使用输出模式准备能力结果。直接以 PHP 调用 $ability->execute() 时,仍会返回回调结果,而不会执行此 JSON 表示步骤。序列化结果的自定义传输应在编码前使用能力的输出模式准备结果。

此准备过程不会执行完整的模式验证,也不会填充缺失的默认值。它只会改变现有值的表示形式。当匹配的模式允许数组时,空数组仍为 [];同时允许对象和数组的模式不会强制将其变为 {}。

集成开发者应做的更改

能力作者应在输出模式中明确声明 type: object 或 type: array,包括空值很重要的嵌套属性。消费对象模式的客户端应预期空结果为 {}。请更新依赖在这种情况下接收到 [] 的代码。声明为数组的结果将继续使用 []。

对于自定义传输层,请在进行 JSON 编码之前立即准备成功结果。这里,$ability 是已经解析的 WP_Ability,$raw_input 是调用方的输入:

bash 复制代码
$result = $ability->execute( $raw_input );

if ( is_wp_error( $result ) ) {
    return $result;
}

return wp_json_encode(
    wp_prepare_json_value_for_client(
        $result,
        $ability->get_output_schema()
    )
);

该辅助函数会保留模式的 JSON 形状;它不会授予权限或取代执行过程。请让错误走传输层的常规错误路径,而不是将其作为成功结果准备。

更新集成

请审查依赖原始 PHP 类型或未清理输入的回调。检查自定义权限检查路径是否缺少准备步骤;在使用自定义传输层时,请在序列化边界应用 JSON 准备。

支持较早 WordPress 版本的插件必须使用与相应版本匹配的注册参数,保留现有的权限回调,并对新方法和函数的使用进行防护。如果省略权限回调而改用 required_capabilities,则需要 WordPress 7.2。

核心答案

WordPress 7.2 的 Abilities API 通过 required_capabilities 声明通用权限,并统一使用 prepare_input() 验证和清理输入。权限回调与执行回调获得处理后的值,JSON 输出遵循 output_schema。

常见问题

WordPress 7.2 中 required_capabilities 与 permission_callback 应如何使用?

若所需权限适用于每次调用,请填写非空 required_capabilities 并可省略 permission_callback;若权限取决于文章等具体输入,则保留 permission_callback。列表为空或未声明时,必须提供有效权限回调。

为什么 WordPress 7.2 的 number 模式会把整数 10 转成 10.0?

Abilities API 为确保直接 PHP 调用与 REST 请求行为一致,会按模式转换 number 类型。需要整数时应使用 integer 模式,并让 number 回调接受浮点数。

调用 check_permissions() 前为什么必须先执行 prepare_input()?

check_permissions() 不会自行准备输入。prepare_input() 会应用默认值、验证并清理原始数据;失败时应立即返回 WP_Error,避免权限回调收到未经处理的值。

{"@context":"https://schema.org","@type":"Article","headline":"WordPress 7.2 更新 Abilities API,统一权限检查、输入处理与 JSON 输出","description":"介绍 WordPress 7.2 Abilities API 的 required_capabilities、输入准备、模式验证与清理、权限发现筛选及 REST 行为变更。","inLanguage":"zh-CN","author":{"@type":"Organization","name":"SEO/GEO 编辑"},"publisher":{"@type":"Organization","name":"SEO/GEO 编辑"},"mainEntityOfPage":{"@type":"WebPage","@id":"https://example.com/wordpress-7-2-abilities-api"}}

WordPress 7.2 更新了 Abilities API,使权限、输入处理和 JSON 输出更加可预测。Abilities 可以声明每次调用都需要的能力。直接通过 PHP 调用和发送 REST 请求时,会根据能力的模式清理输入,而 JSON 结果会保留模式所声明的对象或数组结构。下面的示例说明了能力作者和集成开发者需要更改的内容。

相关推荐
杨凯凡19 分钟前
IT日报|2026-11-20:欧盟 AI 网络攻击、Valkey 9.2、GitHub 企业迁移
人工智能·github
鲁邦通物联网1 小时前
机器人梯控到站状态机设计:楼层匹配、事件时序与任务判断
人工智能·机器人·机器人梯控·agv梯控·非侵入式采集·机器人乘梯·机器人自主乘梯
静水深码1 小时前
文生图提示词的工程师写法:把玄学话术拆成结构化模板
人工智能·后端·代码规范
Seiran1 小时前
Claude Fable 5.1写技术方案,ZEEKEAI提效实录
人工智能
JonaHu1 小时前
GPT Image 2.6 多语言海报改版:保留商品细节,分离文案与图像验收
图像处理·人工智能·aigc
4cos902 小时前
pi学习笔记-BranchSummary
人工智能
程序员张富华2 小时前
一次发布拦住12个破坏性变更:我们给Agent工作流加了Schema门禁
人工智能·agent
伞伞悦读2 小时前
【第90期】KNN分类回归流水线与K值对照的实验与排查
大数据·人工智能·python·深度学习·机器学习
老余说AI2 小时前
跨境电商、课程出海:六款多语言视频翻译工具选型指南
大数据·运维·人工智能