Composer项目结构优化核心是四点：composer.json须在根目录、vendor/不污染源码、自动加载路径对齐、部署精准剔除无关内容；所有配置与操作必须严格同步命名空间、文件路径及autoload映射。
Composer 项目结构不是“越规范越好”，而是要让 composer.json 能被正确识别、vendor/ 不污染源码、自动加载不绕弯、部署时能精准剔除无关内容——所有优化都围绕这四点展开。
composer.json 必须放在项目根目录，否则命令全失效
Composer 只认当前工作目录下的 composer.json，不会向上查找父目录，也不支持子目录里放多个 composer.json 来“分模块管理”。一旦你把它放进 src/ 或 app/，运行 composer install 就会报错或生成错误的 vendor/ 路径。
所有命令（composer install、composer update、composer dump-autoload）都必须在 composer.json 所在目录执行。如果你用 IDE 自动执行却没注意当前工作目录，就可能在错误位置生成 vendor/，导致类找不到。
- 项目是库（library）：根目录下只放
composer.json、src/、tests/、README.md，绝不能有vendor/ - 项目是应用（application）：根目录下可有
public/、config/、bin/，但vendor/必须与composer.json同级 -
vendor/必须被.gitignore排除，但composer.lock不能丢 —— 它是生产环境依赖一致性的唯一依据
PSR-4 autoload 配置必须和文件系统、命名空间三者对齐
常见错误不是“写错了”，而是“改了这里忘了那里”：比如把目录从 src/Controllers/ 改成 src/Http/Controllers/，却没同步更新 composer.json 里的 "psr-4" 值；或者类文件里写的 namespace AppHttpControllers;，而映射前缀却是 "App\": "src/"，结果自动加载器拼出的路径是 src/Http/Controllers/UserController.php，但实际文件在 src/Controllers/UserController.php，直接报 Class not found。
src/ 下不能混放不同命名空间的类。例如，src/Database/Connection.php 声明 namespace AppDatabase;，而 src/Database/Seeder.php 却声明 namespace IlluminateDatabase;，会导致自动加载器在 App 映射下找不到后者，或误加载前者。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 检查方式：运行
composer dump-autoload -v，看输出里是否列出你期望的类路径 - 验证方式：用
composer show --path vendor/package-name确认包安装位置，再比对autoload_psr4.php中的映射是否生效 - 开发时用
composer dump-autoload -o加速，但上线前务必确认-o不会漏掉动态注册的类（比如某些测试工具依赖的反射类）
生产环境必须启用优化自动加载，但要注意权威模式的副作用
"optimize-autoloader": true 和 "classmap-authoritative": true 是生产环境标配，它们会让 Composer 生成 autoload_classmap.php 并跳过 PSR-4 目录扫描，大幅减少 I/O 开销。但问题在于：如果项目里存在运行时动态拼接类名（如 $class = 'App\' . $suffix;）、class_alias()、或通过 ReflectionClass 加载未在代码中显式引用的类，这些类就不会被收录进 classmap，启动时直接报错。
这不是配置错了，而是你的代码逻辑和自动加载机制不兼容。Laravel 的 Service Provider、Symfony 的 bundle 注册、甚至某些配置驱动的扩展，都依赖这种“非静态引用”方式，classmap-authoritative 会直接让它们失效。
- 上线前必须跑一遍完整功能流程（包括后台任务、队列、命令行脚本），不能只测首页
- CI 流水线中建议加一步：
php -d display_errors=1 -d error_reporting=-1 -r "require 'vendor/autoload.php';"，提前暴露 classmap 缺失问题 - 若必须用动态类加载，可保留
"classmap-authoritative": false，但需接受约 20–30ms 的加载开销增长
清理无用依赖不能只信 composer-unused
composer-unused 是第三方工具，它靠静态扫描 use、new、class_exists() 等调用点来推测依赖是否被使用，但漏报率高。动态加载类（__autoload、spl_autoload_register）、反射调用、字符串拼接类名、测试代码（tests/ 默认不扫描）、Service Provider 注册，全都不在它的检测范围内。
更可靠的方式是组合验证：先用 composer-unused 列出候选，再用 grep -r "Vendor\Package" src/ app/ --include="*.php" 手动确认，最后运行 composer depends vendor/package-name 查依赖链 —— 如果没有其他已安装包依赖它，且 grep 无结果，才真正安全移除。
- 执行
composer remove vendor/package-name后，必须立刻运行composer dump-autoload -o，否则旧 PSR-4 映射仍留在autoload_psr4.php中，类还能加载成功，造成“删了但还在”的错觉 - 移除后检查
vendor/composer/autoload_*.php，确认目标包的路径和命名空间已彻底消失 - 若
composer remove报错说“被其他包依赖”，别硬删，先查依赖链：composer depends --tree vendor/package-name
最常被忽略的一点：项目结构优化不是一次性动作，而是持续校验的过程。每次重命名目录、移动类文件、修改命名空间，都必须同步更新 composer.json autoload 配置，并重新运行 dump-autoload；每次上线前，都要确认 composer.lock 已提交、vendor/ 未被误提交、且 --no-dev 在 CI 中被严格执行。这些细节不体现在架构图里，但决定着部署是否能过第一关。
