PHP 8.2 枚举实现后台角色权限：拒绝默认、策略映射与审计日志

后台导出接口最近多了一条奇怪日志：角色字段是 auditor，接口却按“没有匹配规则”继续执行了查询。问题不在 PHP 的枚举语法本身，而在权限代码把未知值当成了一个可以正常往下走的普通分支。用 PHP 8.2 的 backed enum 表达角色和动作，再配一张显式策略表，能让新增角色、拦截非法默认值和审计记录都变成可校验的代码边界。

权限判断的底线是：角色和动作先完成解析，任何未注册值都直接拦截；只有通过策略映射的合法组合才允许进入后续业务函数。

权限判断为什么不能靠散落的字符串判断

最初的实现往往写得很随意：if ($role === 'admin')，再加几个零散的 in_array()。当角色取值来自数据库、动作标识来自路由名时，拼写错误不会在部署阶段提前暴露，甚至可能因为默认值处理不严谨而误放行。

下面这两个枚举只描述系统认可的合法取值，不替上层业务做权限决策：

数据库读出的字符串要经过 Role::tryFrom() 做合法性校验，不要直接裸把字符串强制转换成枚举。tryFrom() 返回 null 时，说明这个值根本不在当前权限模型的定义范围内，调用方应该立刻终止后续请求处理。

把角色与动作收拢到显式策略映射

权限策略适合做成“角色对应允许动作”的只读映射表。这里不把 admin 写成万能通配符，避免后续新增敏感动作时，旧角色无意继承了全部操作权限。

final class PermissionPolicy
{
    /** @return array */
    public static function allowed(Role $role): array
    {
        return match ($role) {
            Role::Admin => [
                Action::OrderRead->value => true,
                Action::OrderExport->value => true,
                Action::UserManage->value => true,
            ],
            Role::Operator => [
                Action::OrderRead->value => true,
            ],
            Role::Auditor => [
                Action::OrderRead->value => true,
            ],
        };
    }

    public static function allows(Role $role, Action $action): bool
    {
        return isset(self::allowed($role)[$action->value]);
    }
}

match 没有写默认分支是刻意设计的：如果后续新增一个角色却忘记补充对应的权限策略，测试阶段就会直接报错暴露问题，而不是静默按旧逻辑兼容处理。业务入口只接收已经解析完成的枚举类型参数：

function authorize(string $rawRole, string $rawAction): Role
{
    $role = Role::tryFrom($rawRole);
    $action = Action::tryFrom($rawAction);

    if ($role === null || $action === null) {
        throw new RuntimeException('permission value is not registered');
    }
    if (!PermissionPolicy::allows($role, $action)) {
        throw new RuntimeException('permission denied');
    }
    return $role;
}

控制器捕获拒绝异常后返回统一的 403 响应。不要把“没有找到对应角色”和“角色没有该操作权限”这两种场景都返回成 500 错误；前者应该单独触发告警，因为它大概率是底层数据异常或者发布配置出错导致的。

权限日志要能直接回答谁、做了什么、为什么被拒绝

审计日志和普通应用调试日志的定位完全不同。一次权限拒绝操作至少要保留请求 ID、账号 ID、原始角色取值、原始动作标识、解析状态和策略匹配结果，方便后续把权限故障和用户的实际业务操作串起来溯源。

function auditPermission(
    LoggerInterface $logger,
    string $requestId,
    int $userId,
    string $rawRole,
    string $rawAction,
    ?Role $role,
    ?Action $action,
    bool $allowed,
): void {
    $logger->warning('permission decision', [
        'request_id' => $requestId,
        'user_id' => $userId,
        'raw_role' => $rawRole,
        'raw_action' => $rawAction,
        'role' => $role?->value,
        'action' => $action?->value,
        'allowed' => $allowed,
    ]);
}

日志里不要存放 Cookie、Authorization 请求头、密码或者完整表单内容。原始角色和动作属于排查问题的有效证据，但也要限制字段长度，按结构化字段写入，不要直接把用户可控文本拼接到普通日志行里。

发布前用测试锁住拒绝默认的逻辑

权限测试不只验证管理员账号能正常访问资源，还要专门校验未知值、策略缺口和敏感动作这些边界场景。数据驱动用例可以把这组校验逻辑写得非常清晰直白：

$cases = [
    ['admin', 'user.manage', true],
    ['operator', 'order.export', false],
    ['auditor', 'order.read', true],
    ['auditor', 'user.manage', false],
    ['guest', 'order.read', false],
    ['admin', 'user.delete', false],
];

foreach ($cases as [$role, $action, $expected]) {
    $parsedRole = Role::tryFrom($role);
    $parsedAction = Action::tryFrom($action);
    $actual = $parsedRole !== null
        && $parsedAction !== null
        && PermissionPolicy::allows($parsedRole, $parsedAction);
    assert($actual === $expected, "$role/$action mismatch");
}

真实项目可以用 PHPUnit 的数据提供器来批量跑这类用例，同时把异常类型、HTTP 403 状态码、审计事件字段的正确性一并做断言校验。上线前再手动请求一次导出接口做验证：合法角色返回 200 状态，未知角色返回 403 状态，日志里能用同一个 request_id 快速定位到对应的拒绝原因。

常见问题

枚举能替代数据库里的角色表吗？

不能。枚举适合表达代码层面认可的固定取值边界，数据库仍然用来存储用户、组织和角色的关联关系。两者之间要在解析层做好清晰的失败处理逻辑。

为什么不在策略里加一个 default => false 的兜底？

权限策略更需要主动暴露遗漏，而不是静默隐藏遗漏。对未知输入应该在解析阶段就直接拦截；对新新增的枚举 case，应该让测试或者静态检查工具提醒开发者补齐对应的策略配置。

审计日志是否应该记录完整请求参数？

通常不建议。只记录定位决策所必需的字段，同时对原始字符串做长度限制和敏感字段过滤；完整请求内容应该存放到受控的独立安全审计系统里，而不是普通应用日志中。

把权限边界变成可复查的发布项

这套写法的价值不在于枚举本身，而在于把“未知值该怎么处理”写成了完全无法绕过的固定执行路径。发布前检查三件事：所有角色和动作都有明确的合法来源；策略映射没有隐式通配逻辑；403 响应和审计事件能用请求 ID 一一对应。满足这三个条件，权限代码才算从“能跑通”的状态升级成可长期维护的状态。