Yii2 提供了 GroupUrlRule 类，可通过其 prefix 属性为一组路由规则的匹配路径（即规则数组的键）自动添加公共前缀，避免重复书写如 'api/...'，大幅提升大规模路由配置的可维护性。
yii2 提供了 `groupurlrule` 类，可通过其 `prefix` 属性为一组路由规则的匹配路径（即规则数组的键）自动添加公共前缀，避免重复书写如 `'api/...'`，大幅提升大规模路由配置的可维护性。
在 Yii2 应用中，当需要为大量 URL 规则统一添加路径前缀（例如所有 API 路由均以 /api 开头），手动在每条规则的 key 中重复写 'api/...' 不仅冗余，更易出错且难以维护——尤其当规则数量达数百条时。此时，不应依赖 .htaccess 重写（它作用于 Web 服务器层，无法影响 Yii 的内部路由解析逻辑），而应使用框架原生支持的路由分组机制。
Yii2 内置的 yii\web\GroupUrlRule 正是为此场景设计：它允许你将一组子规则包裹在一个逻辑分组中，并通过 prefix 属性自动为所有子规则的 pattern（即规则键）添加统一前缀。该前缀仅作用于路由匹配路径（key），不影响 route 值（value）的解析。
✅ 正确用法示例
在 config/web.php 的 urlManager 配置中，使用 GroupUrlRule：
'urlManager' => [
'enablePrettyUrl' => true,
'showScriptName' => false,
'rules' => [
// 其他非 API 规则（如首页、后台等）
'' => 'site/index',
'<controller>/<action>' => '<controller>/<action>',
// ? 使用 GroupUrlRule 统一管理所有 /api/* 路由
new \yii\web\GroupUrlRule([
'prefix' => 'api', // ← 关键：所有子规则 key 自动前置 'api/'
'rules' => [
'' => '_public/site/index', // 匹配 /api → 实际生效为 'api' => '_public/site/index'
'<controller>/<action>' => '_public/<controller>/<action>',
'v1/user/<id:\d+>' => '_public/v1/user/view',
'health' => '_public/site/health',
// ... 可扩展至数百条，无需再写 'api/' 前缀
],
]),
// 其他分组（如 admin、mobile）可同理定义
],
],? 注意：GroupUrlRule 的 prefix 仅拼接至子规则的 pattern（左侧 key）。例如子规则 '<controller>/<action>' 将被自动映射为 api/<controller>/<action>，与手动书写 'api/<controller>/<action>' => '...' 效果完全一致。
⚠️ 重要注意事项
- 根路径处理：若需匹配 /api（即空路径），直接在 rules 数组中写 '' => '...' 即可（如上例所示），GroupUrlRule 会将其正确解析为 api 路径。
- 优先级顺序：GroupUrlRule 本身是一条规则，其匹配优先级取决于它在 rules 数组中的位置。建议将高优先级的精确规则（如 api 根路径）放在分组内靠前位置，或确保分组规则位于通用通配规则（如 <controller>/<action>）之前，避免被提前匹配。
- 不支持嵌套分组：GroupUrlRule 的 rules 子项不能再包含 GroupUrlRule（Yii2 当前版本不支持递归嵌套），但可通过多个并列 GroupUrlRule 实现多级前缀（如分别定义 prefix => 'api' 和 prefix => 'admin'）。
- 性能无损耗：GroupUrlRule 在应用启动时完成模式预编译，运行时匹配效率与普通规则一致，无需担心性能问题。
✅ 总结
使用 GroupUrlRule 是 Yii2 中实现 URL 路径前缀集中管理的标准、高效且可扩展的方案。它从架构层面解耦了路径结构与业务路由逻辑，显著提升大型项目路由配置的清晰度与可维护性。相比 .htaccess 或自定义重写规则，该方式完全基于框架能力，兼容性好、调试直观、部署简单——是处理“500 条 API 路由前缀”类需求的首选实践。
