如何通过Yii框架的权限路由实现基于路由的访问控制管理？

本文共计1600个文字，预计阅读时间需要7分钟。

`AccessControl 过滤器是 Yii 控制器的一部分，用于实现权限控制。它不是用来试图图解问题的，也不会涉及数字游戏，直接输出结果不超过100字：

常见错误现象：未登录用户访问 /admin/dashboard 时直接报 403 或白屏，而不是跳转到 /site/login；或者登录后仍被拦在首页外。

• 必须显式声明 'only' => ['index', 'create', 'update'] 或 'except' => ['login', 'request-password-reset']，否则默认对整个控制器所有 action 生效
• 'user' => ['@'] 表示“已登录”，['?'] 表示“未登录”，二者不能混用在同一 rule 中；想实现“登录用户可看，未登录跳登录页”，就得靠两个 rule 嵌套顺序
• rule 的执行顺序很重要：Yii 按数组顺序逐条匹配，第一条命中即终止；把 ['actions' => ['login'], 'allow' => true] 放在最前面，否则会被上游的 ['user' => ['@']] 拦住
• 如果用了模块（如 admin），AccessControl 要写在模块内的控制器里，不是主应用的 SiteController；否则路由根本进不到该过滤器

rbac 权限和路由怎么绑定才不重复插入 auth_item

RBAC 中权限（auth_item.type = 2）和路由（auth_item.name 以 / 开头）本质是同一张表里的不同记录，但很多人手动 insert 或用 Gii 批量生成时，把路由当权限加，导致 auth_item_child 关系错乱。

典型错误：执行 $auth->createPermission('/admin/user/index') —— 这是错的。路由本身不是权限，它只是路径标识；真正要创建的是业务语义权限，比如 manageUser，再通过 addChild() 把它和路由关联。

• 先确保 urlManager->enablePrettyUrl 已开启，否则路由名解析会出问题（如 admin/user/index 可能变成 admin%2Fuser%2Findex）
• 添加路由权限前，先调用 $auth->addRoute('/admin/user/index')（需自定义或扩展 AuthManager，原生不提供该方法），或更稳妥地：用 yii\rbac\DbManager 配合 migration 插入 auth_item 记录，name 字段填 /admin/user/index，type 设为 1（角色）或 2（权限）——但注意：路由类条目应设为 type=2，且 description 写清楚用途
• auth_item_child 是父子关系表，一条记录表示“父权限包含子项”；若把 manageUser → /admin/user/index 加进去，那检查 $user->can('manageUser') 时才会触发该路由权限
• 避免用后台界面反复点击“分配路由”，它可能重复写入相同 auth_item，建议用 migration 统一管理初始权限集

用户 can() 检查时传参不生效？规则（Rule）没跑起来

Yii::$app->user->can('updatePost', ['post' => $model]) 看似简单，但参数传进去后 Rule::execute() 根本没被调用，说明权限没挂规则，或规则条件写错了。

最容易被忽略的一点：规则类必须在 auth_item 表中注册为 type = 3，且权限项（updatePost）的 rule_name 字段必须精确等于该规则类名（如 PostAuthorRule），大小写、命名空间都不能差。

• 规则类必须继承 yii\rbac\Rule，且 execute() 方法返回布尔值；别在里头 throw 异常，那会导致整个 can() 报错而非静默拒绝
• execute() 的第三个参数 $params 就是你传进来的 ['post' => $model]，但注意：$model 必须是已加载的 ActiveRecord 实例，不能是 ID 或空对象，否则 $params['post']->author_id 会报错
• 调试时可在 execute() 开头加 file_put_contents('/tmp/rule.log', print_r($params, 1), FILE_APPEND) 确认是否触发；没日志就说明权限项没绑规则，或 AuthManager 缓存没刷新（php yii rbac/flush）
• 规则只在运行时起作用，不影响数据库查询性能；但别在里面做 heavy query，比如查用户组织树三层深，应提前缓存或预加载

模块内路由权限控制为什么总是 404 或无反应

模块（Module）自带独立命名空间和路由前缀，但 AccessControl 和 RBAC 权限配置若还按主应用习惯写，就会失效或 404。

典型症状：访问 /admin/user/index 报 404，但控制器存在；或 $user->can('adminManage') 始终返回 false，即使已分配角色。

• 模块控制器的 behaviors() 必须在模块内部的控制器类里定义，不能只在 SiteController 或全局 bootstrap 里配；否则请求根本不会经过该行为
• RBAC 权限名不要带模块前缀（如别用 admin/update-user），统一用语义名（updateUser），然后在规则或 auth_item_child 里关联具体路由
• 模块 ID（如 admin）必须和 URL 第一段完全一致（admin/user/index），且大小写敏感；Linux 下 Admin 和 admin 是两个模块
• 如果模块启用了自定义 defaultRoute（如 $this->defaultRoute = 'dashboard/index'），记得在权限检查时也覆盖这个路径，否则 /admin 请求可能被当成 /admin/dashboard/index，而你只给 /admin/user/index 分了权限

实际项目里最麻烦的从来不是写几行 can() 或配个 AccessControl，而是权限边界模糊：一个路由该算“功能入口”还是“数据操作”？规则里要不要校验用户所属部门？这些没法靠框架自动推断，得在第一次建 auth_item 表时就定好命名规范和层级粒度。