Yii框架REST鉴权方法与AccessControl使用技巧

Yii2的AccessControlFilter因依赖session登录态而无法适配RESTful接口的无状态token认证，导致常见403错误和身份识别失效；正确方案是采用authenticator（如HttpBearerAuth）与access组合，确保先完成token解析并设置user identity，再执行基于RBAC权限的访问控制，同时需注意行为注册顺序、RBAC缓存同步及CORS头配置等关键细节，才能构建稳定可靠的REST鉴权体系。

RESTful接口不能直接用 AccessControlFilter 的原因

Yii 的 AccessControlFilter（ACF）默认依赖 yii\web\User 的 session 登录态，而 REST 场景下多数用 token（如 Bearer JWT）或无状态认证，User::isGuest 和 User::identity 在未配置 enableSession => false 且未重写认证逻辑时会失效，导致 'roles' => ['@'] 永远不通过。

典型现象：API 返回 403，日志里没报错，但 Yii::$app->user->isGuest 始终为 true，哪怕请求头带了 Authorization: Bearer xxx。

• ACF 的 'users' => ['@'] 底层调的是 User::getIsGuest()，它只看 session 或 cookie，不解析 Authorization 头
• REST 控制器通常继承 yii\rest\Controller，它默认不启用 session，User 组件无法自动从 token 构建 identity
• 即使你手动在 beforeAction 里解析 token 并赋值 Yii::$app->user->setIdentity($identity)，ACF 仍可能因执行顺序问题读不到最新状态

正确做法：用 authenticator + access 组合替代 ACF

Yii2 REST 模块内置了更适配的鉴权链路：authenticator 负责身份识别（如从 header 提取并验证 token），access 负责权限判断（复用 RBAC）——二者可共存，且顺序可控。

在控制器中配置：

public function behaviors()
{
    $behaviors = parent::behaviors();
    // 先做身份认证
    $behaviors['authenticator'] = [
        'class' => \yii\filters\auth\HttpBearerAuth::class,
        // 或 HttpHeaderAuth / QueryParamAuth，按需选
        'except' => ['options'], // CORS 预检跳过
    ];
    // 再做权限控制（注意：必须放在 authenticator 之后）
    $behaviors['access'] = [
        'class' => \yii\filters\AccessControl::class,
        'rules' => [
            [
                'allow' => true,
                'actions' => ['index', 'view'],
                'roles' => ['?'], // 匿名可访
            ],
            [
                'allow' => true,
                'actions' => ['create', 'update'],
                'roles' => ['createPost', 'updatePost'], // 对应 RBAC permission 名
            ],
        ],
    ];
    return $behaviors;
}

• authenticator 必须在 access 之前注册，否则 Yii::$app->user->identity 还是 null，can() 调用必返回 false
• roles 数组里写的仍是 permission 名（如 'createPost'），不是角色名；RBAC 数据必须已初始化且缓存同步
• 若用自定义 auth 方案（如 API key 查库），需继承 \yii\filters\auth\AuthMethod 实现 authenticate()，不能只靠改 User 组件

accessRules() 在 REST 控制器里基本无效

老式写法（重写 accessRules()）在 yii\rest\Controller 中不会被自动调用，因为 REST 模块默认不注册 accessControl 过滤器 —— 它只认 behaviors() 返回的配置。

常见错误：

• 写了 public function accessRules() 却没在 behaviors() 里显式启用 AccessControl，规则完全不生效
• 沿用 CController 时代的写法，把 'users' => ['@'] 当成万能登录检查，但在 REST 下它只查 session，和 token 无关
• 混用 'roles' 和 'permissions' 键名：ACF 只认 'roles'，写成 'permissions' => [...] 会被忽略

高频踩坑点：RBAC 缓存与动态分配不同步

你在后台给用户分配新 permission 后，API 立即调用 Yii::$app->user->can('xxx') 仍返回 false，大概率是缓存没清。

• RBACK 默认不开启缓存，但很多项目会配 'cache' => 'cache' 在 authManager 配置里；一旦开了，增删 assignment 后必须手动清缓存：Yii::$app->cache->delete('rbac_assignments_' . $userId)
• DbManager 下，can() 查询会走 auth_assignment 表，但如果用了 query cache（比如 MySQL 的 query_cache_type=1），表数据更新后缓存可能延迟失效
• 测试时用 curl -H "Authorization: Bearer xxx" 成功，但前端发请求失败？检查是否漏了 Access-Control-Allow-Headers: Authorization，预检失败会导致 authenticator 根本不执行

真正麻烦的从来不是写几行配置，而是 token 解析、identity 绑定、RBAC 查询、缓存刷新这四步之间的时间差和隐式依赖。

理论要掌握，实操不能落！以上关于《Yii框架REST鉴权方法与AccessControl使用技巧》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！