Yii2中controller下建二级子目录合法常用，关键在命名空间、文件路径、URL三者严格匹配；如controllers/api/MemberController.php需声明namespace app\controllers\api，对应URL为/api/member/index。
Yii2 中 controller 目录下建二级子目录是合法且常用的做法
直接在 controllers 下新建子目录（如 api/、admin/）完全可行，不需要改框架源码或 hack 路由。关键在命名空间和 URL 路径的对应关系必须严格匹配。
控制器类的命名空间必须反映真实目录结构
比如你创建了 controllers/api/MemberController.php，它的命名空间就必须是 app\controllers\api，不能写成 app\controllers 或漏掉 \api。否则 Yii 找不到类，报 Class 'app\controllers\api\MemberController' not found。
- 文件路径：
controllers/api/MemberController.php - 命名空间声明：
namespace app\controllers\api; - URL 访问地址：
/api/member/index（默认 action）或/api/member/test - 注意大小写：目录名
api和命名空间中的api必须全小写，Windows 下可能不敏感，Linux 服务器会直接 404
路由能自动识别，但别依赖“隐藏规则”
Yii2 默认启用 enablePrettyUrl = true 后，/api/member 这种路径会被自动解析为 app\controllers\api\MemberController 的 actionIndex。它不是靠配置“猜”的，而是基于命名空间 + 类名 + 文件路径三者一致的约定。
- 不要手动在
urlManager.rules里为每个二级控制器加一条 rule，那是冗余且易错的 - 如果遇到 404，优先检查：文件是否存在、命名空间是否拼错、类名是否以
Controller结尾、是否用了use yii\web\Controller - 调试时可临时加一句
var_dump(class_exists('app\controllers\api\MemberController'));确认类是否被正确加载
模块（Module）和二级目录是两套不同机制，别混用
二级目录控制器（如 controllers/admin/UserController）和 Module（如 modules/admin/Module.php）解决的问题不同。前者只是组织代码，后者自带独立配置、视图路径、权限域等完整上下文。如果你只是想把后台控制器归类，用二级目录就够了；如果需要隔离路由前缀、独立语言包或 RBAC 权限范围，才该上 Module。
- 二级目录控制器共享主应用的
viewPath，模板要放在views/admin/user/index.php - Module 的视图默认在
modules/admin/views/...，且Module::className()必须注册进应用配置的modules数组 - 一个常见坑：把
controllers/api/UserController.php当成 Module 来配'modules'=>['api'=>...]，结果路由冲突或类重复加载
最易忽略的一点：二级目录控制器的视图文件路径必须和控制器类名层级对齐，controllers/api/ReportController 对应的默认视图是 views/api/report/index.php，少一层目录或拼错名字就会静默失败——它不会报错，只会渲染空白或 fallback 到 layout。
