WordPress REST API基于用户角色的JSON响应高级定制问询

问题背景 #

我正在增强一款WordPress插件，目标是根据用户角色定制REST API端点的JSON响应，动态修改数据序列化，让不同角色访问不同的数据字段集合。重点处理自定义文章类型的响应，覆盖administrator、editor、subscriber及guest等角色。

现有实现使用rest_prepare_<post_type>钩子，但存在性能差、扩展性不足的问题：

function role_based_api_response( $response, $post, $request ) {
    $data = $response->get_data();
    switch (true) {
        case current_user_can('administrator'):
            // No modification for admins
            break;
        case current_user_can('editor'):
            // Editors can't see 'admin_notes'
            unset($data['admin_notes']);
            break;
        case current_user_can('subscriber'):
            // Subscribers only see 'title' and 'summary'
            $data = [
                'title' => $data['title'],
                'summary' => $data['summary']
            ];
            break;
        default:
            // Guests see only 'title'
            $data = ['title' => $data['title']];
    }
    $response->set_data($data);
    return $response;
}
add_filter( 'rest_prepare_my_custom_post', 'role_based_api_response', 10, 3 );

需要解决三个核心问题：

1. 如何重构代码优化性能，应对大量API调用？
2. 如何用动态方法或设计模式替代大量switch/if语句？
3. WordPress是否有更深层级的钩子或函数，更集成化处理REST响应序列化？

解决方案 #

1. 性能优化策略 #

• 缓存用户角色权限：提前获取并缓存当前用户的角色集合，减少current_user_can的调用次数（该函数会触发数据库查询），避免重复判断。
• 按需字段过滤：优先保留允许的字段而非先序列化所有字段再删除，减少数据处理量；使用array_intersect_key替代重置整个数组，降低内存开销。
• 减少重复计算：将角色权限规则缓存到内存中，避免每次API调用都重新生成配置数组。

2. 基于配置的规则模式（替代switch/if） #

通过配置数组定义角色与字段的映射规则，实现动态扩展——新增角色或修改字段权限只需调整配置，无需改动核心过滤逻辑：

// 定义角色-字段权限配置（可独立到配置文件或数据库选项）
function get_role_field_permissions() {
    // 缓存配置，避免重复生成数组
    static $permissions;
    if (isset($permissions)) return $permissions;

    $permissions = [
        'administrator' => [
            'type' => 'allow_all', // 允许所有字段
        ],
        'editor' => [
            'type' => 'deny_list',
            'fields' => ['admin_notes'] // 禁止的字段
        ],
        'subscriber' => [
            'type' => 'allow_list',
            'fields' => ['title', 'summary'] // 允许的字段
        ],
        'guest' => [
            'type' => 'allow_list',
            'fields' => ['title']
        ]
    ];
    return $permissions;
}

// 获取当前用户的有效角色（处理多角色，取最高权限优先级）
function get_current_effective_role() {
    static $role;
    if (isset($role)) return $role;

    $user = wp_get_current_user();
    if (empty($user->roles)) {
        $role = 'guest';
        return $role;
    }

    // 按权限从高到低排序，匹配第一个生效角色
    $role_priority = ['administrator', 'editor', 'subscriber'];
    foreach ($role_priority as $priority_role) {
        if (in_array($priority_role, $user->roles)) {
            $role = $priority_role;
            return $role;
        }
    }

    $role = 'subscriber';
    return $role;
}

// 核心响应过滤函数
function role_based_api_response( $response, $post, $request ) {
    $permissions = get_role_field_permissions();
    $role = get_current_effective_role();
    $rules = $permissions[$role] ?? $permissions['guest'];
    $data = $response->get_data();

    switch ($rules['type']) {
        case 'deny_list':
            foreach ($rules['fields'] as $field) {
                if (isset($data[$field])) {
                    unset($data[$field]);
                }
            }
            break;
        case 'allow_list':
            $data = array_intersect_key($data, array_flip($rules['fields']));
            break;
        // allow_all 无需处理
    }

    $response->set_data($data);
    return $response;
}
add_filter( 'rest_prepare_my_custom_post', 'role_based_api_response', 10, 3 );

3. 更深层级的REST序列化钩子 #

WordPress提供了底层钩子，可在字段注册或序列化阶段直接控制可见性，避免批量修改响应数据：

方法1：注册字段时添加权限校验

在register_rest_field的get_callback中直接判断用户权限，无权限则返回null（会被自动过滤出响应）：

register_rest_field( 'my_custom_post', 'admin_notes', [
    'get_callback' => function( $post_arr ) {
        if (current_user_can('administrator')) {
            return get_post_meta($post_arr['id'], 'admin_notes', true);
        }
        return null; // 无权限则不返回该字段
    },
    'schema' => [
        'description' => 'Admin-only notes',
        'type' => 'string'
    ]
] );

方法2：REST初始化时过滤字段

在rest_api_init钩子中，根据角色移除无需展示的字段：

function filter_rest_fields_by_role() {
    $role = get_current_effective_role();
    if (!in_array($role, ['administrator', 'editor'])) {
        // 移除普通用户不可见的字段
        remove_rest_field('my_custom_post', 'admin_notes');
    }
}
add_action( 'rest_api_init', 'filter_rest_fields_by_role' );

方法3：调整rest_prepare_*钩子优先级

将钩子优先级设为9（早于默认的10），在WordPress默认序列化完成后立即处理，减少后续不必要的操作：

add_filter( 'rest_prepare_my_custom_post', 'role_based_api_response', 9, 3 );

额外优化建议 #

• 缓存角色判断结果：使用static变量缓存当前用户的有效角色，避免同一请求内重复计算。
• 兼容多角色场景：按权限优先级处理用户拥有多个角色的情况，确保规则匹配逻辑清晰。
• 字段存在性校验：过滤字段前先检查字段是否存在于响应数据中，避免产生PHP警告。

内容的提问来源于stack exchange，提问作者maxtymosh