Wave Framework 的核心入口点是 public/index.php 中的 Wave::run() 调用，它必须位于文件末尾且前面无任何输出；模块需显式通过 Wave::addModule() 注册，每个模块目录下必须包含返回 WaveModuleInterface 实现类的 Module.php 文件，且 getNamespace() 返回的命名空间须以双反斜杠结尾。
Wave Framework 的核心入口点在哪
Wave Framework 不是靠 index.php 简单包含一堆文件启动的，它的主入口是 public/index.php，但真正驱动路由和模块加载的是 Wave::run() 这个静态调用。如果你把逻辑写在 index.php 里再手动 require 控制器，等于绕过了框架的生命周期，模块自动注册、中间件、依赖注入全失效。
实操建议：
- 确保
public/是 Web 服务器根目录，且.htaccess（Apache）或nginx.conf重写规则已正确配置，所有请求都落到public/index.php - 不要修改
Wave::run()的调用位置——它必须在public/index.php最后一行执行，且前面不能有输出（包括 BOM、空格、echo） - 模块初始化实际发生在
app/config/bootstrap.php中，这里通过Wave::addModule()注册，不是靠文件名或目录自动扫描
模块目录结构怎么组织才被 Wave 正确识别
Wave 不按 PSR-4 自动加载，也不看 src/ 或 Controllers/ 这类通用目录名。它只认你显式声明的模块路径，且每个模块必须含 Module.php 入口文件，否则 Wave::addModule() 会静默失败，控制器完全不响应。
常见错误现象：404 Not Found，但路由定义明明存在；或者 Class 'AppUsersController' not found，其实类文件就在那里，只是没进自动加载链。
立即学习“PHP免费学习笔记（深入）”；
实操建议：
- 模块目录可任意命名（如
app/modules/users/），但内部必须有Module.php，且该文件需返回一个实现WaveModuleInterface的类 -
Module.php中的getNamespace()必须返回完整命名空间（如'App\Users'），结尾双反斜杠不能少，否则自动加载器找不到类 - 控制器类名必须严格匹配路由定义中的字符串，比如路由写
['/users', 'Users:Index']，就要求存在AppUsersControllerIndexController类，且方法是execute()
路由参数和控制器传参为什么总是 null
Wave 的路由参数默认不自动注入控制器属性或方法参数，它只把匹配结果塞进 $this->request->params。如果你习惯 Laravel 那种方法签名绑定（function show($id)），直接照搬会拿到 null。
使用场景：需要从 URL /posts/123/edit 提取 123 并传给编辑逻辑。
实操建议：
- 定义路由时用占位符，如
['/posts/{id}/edit', 'Posts:Edit']，Wave 会把{id}值存入$this->request->params['id'] - 控制器中统一用
$this->request->params取值，别依赖构造函数或方法参数自动解析 - 如果要验证参数类型或默认值，得自己写逻辑，例如：
$id = (int) $this->request->params['id'] ?: 0;，框架不提供required|integer这类规则
如何让自定义类被自动加载而不报 Class not found
Wave 默认只加载模块命名空间下的类（由 Module::getNamespace() 返回的前缀），其他工具类、服务类、实体类不会自动注册。直接 new 一个 AppServicesUserService 就会出错，不是 Composer 没配好，而是 Wave 根本没告诉 PHP 去哪找这个命名空间。
性能影响：手动 require 或 include 会导致每次请求重复加载，破坏 opcode 缓存效果；而用 Composer 自动加载能复用已编译字节码。
实操建议：
- 在
composer.json的"autoload"下添加 PSR-4 映射，例如："App\Services\": "app/services/" - 运行
composer dump-autoload，确保生成的vendor/autoload.php被public/index.php引入（Wave 默认已包含） - 避免在
Module.php中用require_once加载同类，这会绕过 Composer 的优化，也容易引发重复定义错误
Module.php 的命名空间返回格式和 composer.json 的 autoload 配置——这两处差一个字符，整个模块就处于不可见状态。 
