直接在控制器写 actionIndex() 不够用，因其难以维护分页、过滤、权限校验等逻辑；应通过 actions() 方法配置自定义 Action 类，严格遵循命名空间、继承 yii\base\Action、实现 run() 方法，并与 ActiveController 生命周期协同。
为什么直接在控制器里写 actionIndex() 不够用
当你需要为 RESTful 接口提供分页、过滤、权限校验或统一响应格式时，actionIndex() 这类内联方法会快速变得臃肿。比如你要给 GET /api/posts 加上 page 和 per-page 参数处理，还要兼容 expand=user 关联加载，逻辑一多，控制器就难维护、难测试、难复用。
这时候必须把动作逻辑抽离——不是为了“高大上”，而是因为 Yii 的 actions() 方法天然支持参数注入、统一中间件（如 authenticator）、以及与 ActiveController 生命周期无缝对接。
actions() 返回数组里怎么配自定义 Action 类
关键不是“怎么写类”，而是“怎么让控制器认出它并传参”。常见错误是只写类名，漏掉配置项或命名空间不匹配。
- 类必须继承
yii\base\Action，且必须实现run()方法（哪怕空着也会报错） - 在
actions()数组中，键是 action ID（如'list'），值是配置数组，不是字符串类名（除非是简单无参场景） - 配置数组里
'class'是必需的，其他字段（如'modelClass'、'checkAccess'）会被自动赋值给 Action 实例属性 - 路径和命名空间必须严格对应文件物理位置，例如
'class' => 'app\actions\PostListAction'要求文件在@app/actions/PostListAction.php
示例配置：
public function actions()
{
return [
'list' => [
'class' => 'app\actions\PostListAction',
'modelClass' => Post::class,
'pageSize' => 20,
'defaultSort' => ['created_at' => SORT_DESC],
],
];
}
自定义 Action 里怎么拿到请求参数和当前控制器
$this->controller 是你访问控制器上下文的唯一入口，但容易忽略两点：一是它可能为 null（极少见，但单元测试时可能），二是它的 id、route、module 都可直接用；请求参数则不能靠 Yii::$app->request->get() 硬取，而应利用 run() 方法签名自动绑定。
-
run()方法参数名会自动映射 GET/POST 键名，比如run($page = 1, $per_page = 10)会接收?page=2&per_page=5 - 若需原始 request 对象，用
$this->controller->request（比全局Yii::$app->request更安全，避免 mock 困难） - 权限检查不要写死在
run()里，应复用ActiveController::checkAccess()，通过配置'checkAccess' => [$this, 'checkAccess']注入 - 返回数据统一走
return $this->controller->asJson(...)，别直接echo或exit
和 ActiveController 配合时最容易踩的坑
很多人以为重写了 actions() 就能绕过 ActiveController 的默认行为，其实不然——index、view 等默认 action 仍受其 behaviors() 控制。如果你在 actions() 里覆盖了 'index'，但没同步处理 authenticator 或 rateLimiter，接口就可能跳过鉴权或限流。
- 务必调用
parent::actions()再 unset 或覆盖，否则丢失默认配置（比如Cors行为） - 如果禁用某个默认 action（如删掉
'delete'），记得在behaviors()里也移除对应行为，否则 405 错误会误导前端 -
ActiveController默认对index和view自动加Content-Range头，你的自定义 Action 若返回分页数据，得手动设置Range响应头，否则前端无法正确解析 - 调试时看日志别只盯
run()，要查beforeAction()是否被ActiveController的行为拦截了
真正麻烦的从来不是写一个 run()，而是让这个 run() 在整个 REST 生命周期里不被框架其他部分悄悄覆盖或忽略。
