模块拆分应以业务生命周期、数据边界和访问入口为唯一判断标准，合格模块如用户中心、后台管理等具备独立部署与监控能力；反例是仅封装工具方法的CacheModule或UtilsModule，应归入helpers目录而非模块机制。
模块拆分不是为了“看起来模块化”，而是为了解耦业务、控制变更影响范围、支撑团队并行开发。盲目按功能名建模块（比如单独搞个 LogModule 或 HelperModule）反而会增加路由跳转、配置加载和调试成本，最终变成技术债。
哪些业务场景真正适合独立成模块
判断标准只有一个：是否具备独立的生命周期、数据边界和访问入口。常见合格候选：
- 用户中心（
UserModule）：有自己完整的注册/登录/资料/权限流程，数据库表可隔离，前端路由前缀统一为/user - 后台管理（
AdminModule）：控制器不对外暴露，视图布局与前台完全不同，需独立鉴权逻辑和 session 配置 - 开放 API（
ApiV1Module）：对外提供 REST 接口，需独立版本控制、限流、格式化响应，且不渲染 HTML 视图 - 多租户子系统（
TenantModule）：每个租户有独立配置、模型行为、甚至部分表前缀，init() 中动态加载租户上下文
反例：CacheModule（只是封装几个缓存操作）、UtilsModule（只放静态方法）——这类应作为 components 或 helpers 目录下的普通类，不走模块机制。
模块 ID 与类名必须严格对应，否则路由必 404
URL 中第一段路径（如 /admin/dashboard 的 admin）就是模块 ID，它必须和 config/web.php 中 modules 数组的键完全一致，且大小写敏感。
- 注册写成
'Admin' => ['class' => 'app\modules\admin\AdminModule']→ 访问/Admin/dashboard才有效，/admin会 404 - 类文件路径必须匹配命名空间：类
app\modules\admin\AdminModule必须位于@app/modules/admin/AdminModule.php - 控制器 ID 是文件名去掉
Controller后缀的小写形式：文件DashboardController.php对应控制器 IDdashboard，不是Dashboard或dashboard-controller
常见错误现象：Invalid Route – yii\base\InvalidRouteException，本质就是 ID 映射断裂，优先检查 modules 键名、类路径、文件名三者是否完全一致。
子模块嵌套要谨慎，避免路由歧义
Yii 支持在模块内再注册子模块（如 CommentModule 下挂 comment2），但 URL 路由会变成四段式：/comment/comment2/default/index。这种结构极易引发两个问题：
- 路由层级过深，前端 JS 调用时路径拼接易出错
- 子模块无法被主应用直接识别，
\Yii::$app->getModule('comment2')返回 null，只能通过\Yii::$app->getModule('comment')->getModule('comment2')逐级获取 - Gii 生成器不支持嵌套模块创建，所有子模块需手写
Module.php和配置
更稳妥的做法是：把“孙模块”提升为平级模块，用命名空间区分（如 app\modules\comment\v2\CommentV2Module），注册为独立 ID 'comment-v2'，路由回归三段式 /comment-v2/default/index，维护和测试都更清晰。
模块拆分最难的不是代码组织，而是决定“哪里画线”——业务边界一旦模糊，模块就会变成新的耦合容器。每次新增模块前，先问一句：这个功能是否能独立部署、独立配置、独立监控？如果答案是否定的，那就还不到拆的时候。
