yii\rest\UrlRule生效需三要素：启用enablePrettyUrl、urlManager挂载为组件、控制器继承yii\rest\ActiveController；缺一不可。
yii\rest\UrlRule 怎么配才生效
不生效的常见原因是：没启用 enablePrettyUrl，或 urlManager 没挂到应用组件里，或控制器没继承 yii\rest\ActiveController。这三处缺一不可。
必须在 config/web.php 的 components['urlManager'] 中设置：
-
enablePrettyUrl为true -
enableStrictParsing建议设为true（避免模糊匹配导致路由错乱） -
showScriptName设为false（隐藏index.php） -
rules数组中加入['class' => 'yii\rest\UrlRule', 'controller' => ['v1/user']]
注意：controller 值是数组，即使只配一个控制器也要写成 ['v1/user']，不是字符串 'v1/user'；否则会报 Invalid Configuration – yii\base\InvalidConfigException。
pluralize=false 时 URL 和动作怎么对应
默认 pluralize=true，GET /users 映射到 actionIndex，GET /users/123 映射到 actionView。设为 false 后，资源名变单数，但动作映射逻辑不变——只是 URL 看起来更“精简”，不代表语义更准确。
配置示例：
['class' => 'yii\rest\UrlRule', 'controller' => 'user', 'pluralize' => false]
此时：
-
GET /user→actionIndex -
GET /user/123→actionView -
POST /user→actionCreate
⚠️ 容易踩的坑：前端调用时仍按复数习惯写 /users，后端却配了 pluralize=false，结果 404；建议团队统一约定并写进接口文档，别靠“猜”。
extraPatterns 能加哪些自定义动作
extraPatterns 是给 RESTful 默认动作之外补路由的，比如要加一个批量删除、导出 Excel、或软删除标记，就不能靠 actionIndex 或 actionUpdate 覆盖，得显式声明。
写法是键为 HTTP 方法 + 路径模式，值为动作名：
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
['class' => 'yii\rest\UrlRule', 'controller' => 'user', 'extraPatterns' => [
'DELETE batch' => 'batch-delete',
'GET export' => 'export',
]]
对应控制器里就得有 actionBatchDelete() 和 actionExport() 方法。注意路径里的空格不能省——'DELETE batch' 是固定格式，不是正则。
常见错误：
- 写成
'delete batch'（方法名必须大写） - 动作名拼错，如
'batch_delete'（Yii 不会自动转驼峰，必须严格匹配actionXxx） - 漏掉
public访问修饰符，导致 403 或静默失败
URL 版本号怎么透传到控制器里用
单纯把 v1 写死在 controller 键里（如 'v1/user'）只能做模块隔离，没法在同一个控制器里动态响应不同版本逻辑。真要支持多版本共存，得靠路由参数捕获 + 控制器内解析。
推荐做法是在 urlManager 规则中用正则提取版本号：
['class' => 'yii\rest\UrlRule', 'controller' => 'user', 'prefix' => 'api', 'pattern' => '<v1>/<controller:>', 'route' => '<controller>']</controller></controller:></v1>
这样 GET /api/v2/users 会把 version 当作请求参数注入，控制器里可用 Yii::$app->request->get('version') 拿到。
关键点：
- 别依赖
$_GET['version']，要用 Yii 的 request 组件，它已做过滤和类型转换 - 如果同时支持 URL 版本和
Accept头，优先级必须手动在beforeAction()里定清楚，Yii 不自动处理冲突 - 版本参数未提供时，务必设默认值（如
Yii::$app->request->get('version', 'v1')），否则可能触发空指针或 500
最常被忽略的是：路由规则里写了 prefix 或 pattern，但忘了在 rules 数组里把它放在普通规则前面——因为 urlManager 是顺序匹配，靠后的规则可能永远不被执行。
