ThinkPHP跨模块调用目录规范_避免命名冲突的代码组织建议-ThinkPHP-PHP中文网

模块目录名不能和控制器类名同名，否则PSR-4自动加载会因命名空间与路径歧义导致类找不到；模块名须全小写（如admin），控制器用大驼峰（如UserController），冲突时应重命名模块而非类。

thinkphp跨模块调用目录规范_避免命名冲突的代码组织建议

模块目录名不能和控制器类名同名

ThinkPHP 6 默认按 app/模块名/ 组织结构，但如果你建了个模块叫 user，又在里头写了个 UserController，运行时大概率报 Class "app\user\controller\UserController" not found——不是类没加载，是自动加载器把 user 当成命名空间一级，和 app\user\controller 冲突了。

根本原因是 ThinkPHP 的 PSR-4 自动加载规则会把模块名直接映射为命名空间段，而 PHP 命名空间不区分大小写，但文件系统路径区分；一旦模块名和类名（尤其是首字母大写的控制器）拼起来形成歧义路径，composer dump-autoload 就可能漏掉这个类。

模块名统一用全小写、无下划线的英文名词，比如 admin、api、wechat
控制器类名必须以大驼峰开头，且避免和模块名重名，UserController 放 admin 模块没问题，但别放 user 模块
如果已有冲突模块（如 user），不要改类名去迁就，而是重命名模块目录为 usermgr 或 usercenter，再同步更新 config/app.php 中的 default_module 和路由配置

跨模块调用必须显式 use 全限定类名

很多人以为在 app/admin/controller/IndexController.php 里直接写 new UserController() 就能调用 app/user/controller/UserController，结果抛出 Class 'app\admin\controller\UserController' not found。这不是 autoload 失效，是你没告诉 PHP 这个类在哪。

ThinkPHP 不做跨模块自动导入，所有跨模块类引用都得靠 use 显式声明，否则解析器默认按当前命名空间补全。

正确写法是开头加 use app\user\controller\UserController;，然后才能 new UserController()
如果只是调用静态方法（比如 UserModel::getById()），同样要 use app\user\model\UserModel;
切勿用 Loader::import() 或 include 手动加载——这绕过自动加载机制，会导致依赖注入失效、事件监听丢失、以及后续升级时被废弃

模块间模型复用需避开 `app/model/` 全局目录陷阱

有人把所有模型都扔进 app/model/，以为“全局可用”，结果在 admin 模块调用 User 模型时，发现数据表前缀、连接配置还是走默认库，而不是 admin 模块自己配的读写分离配置。

原因在于：ThinkPHP 的模型类若不在模块专属命名空间下（即不是 app\模块名\model\Xxx），框架就不会自动绑定该模块的数据库配置上下文，db()、connection() 等方法都会回落到全局配置。

每个模块需要独立控制数据源的模型，必须放在对应模块目录下，例如 app/user/model/User.php 命名空间为 app\user\model
真正通用的模型（如基础字典、日志），可放 app/common/model/，但要用 use app\common\model\Dict; 显式引入，并手动指定连接：Dict::connect('common_db')
别在 app/model/ 下建子目录模拟模块结构——Composer 的 autoload 配置默认不扫描这里，类根本不会被注册