webman启动强制要求app/controller/和app/middleware/两个目录，缺一则报错退出；控制器类须放controller/下且继承webmancontroller，中间件类须放middleware/下并实现webmanmiddlewareinterface或继承webmanmiddleware。
Webman 启动强制要求的两个目录
Webman 启动时会硬性检查 app/controller/ 和 app/middleware/ 是否存在，缺一不可。哪怕你当前完全不用中间件，也必须保留空的 app/middleware/ 目录，否则执行 php start.php start 会直接报错退出，错误信息类似 Directory not found: app/middleware。
控制器类必须放在 app/controller/ 下，文件名与类名严格一致（如 UserController.php → class UserController），且需继承 WebmanController；中间件同理，必须实现 WebmanMiddlewareInterface 或继承 WebmanMiddleware。
常见错误：把控制器放到 app/controllers/（复数）或 app/Controllers/（大写首字母），框架无法识别，请求 404 且无明确提示；用 IDE 自动生成类时未同步改名，导致类名与文件名不匹配，autoload 失败。
非强制但高频使用的子目录命名规则
app/model/ 和 app/view/ 不是启动必需项，按需创建即可。但一旦使用，路径名必须小写、单数——不能叫 models、Views 或 ViewModels，否则后续通过 config/view.php 中的 view_path 配置无法正确解析模板路径。
其他自定义子目录（如 app/service/、app/traits/、app/exception/）也需遵守小写单数原则。例如：app/Traits/ 是错的，app/traits/ 才对；app/Exceptions/ 会导致 PSR-4 自动加载失败，应为 app/exception/。
注意：目录名错误不会在启动时报错，而是在运行时触发 Class not found，排查成本高。建议用 php console/webman module:create demo 命令生成结构，它输出的目录天然符合规范。
配置文件加载逻辑与陷阱
config/app.php 和 config/database.php 是 Webman 初始化阶段自动加载的唯二配置文件。前者控制框架行为（如 controller_reuse），后者若语法错误或缺失，服务仍能启动，但首次调用 Db:: 时才会抛出异常，容易误判为“数据库连得上但查不出数据”。
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
自定义配置（如 config/cache.php）不会被自动加载，必须显式调用 config('cache') 才生效。所有配置文件必须返回纯 PHP 数组，禁止含 echo、print、BOM 头，也不支持短数组语法以外的写法（如 PHP 5.6 不支持 [] 以外的数组声明）。
环境区分靠 .env + config/bootstrap.php 的手动加载逻辑，不是靠 config/prod/ 这类子目录。试图把配置按环境拆成子目录，会导致配置完全不生效。
Trait 复用时的路径与注入要点
Trait 文件放在 app/traits/ 是推荐做法，但不是强制；关键在于命名空间必须与目录结构严格匹配。例如 app/traits/CrudTrait.php 必须声明 namespace app raits;，并在 composer.json 中确认 "app\": "app/" 的 PSR-4 映射已配置，且执行过 composer dump-autoload。
Trait 内不能直接调用 request()->get()（会报 Call to undefined function request()），控制器需在构造函数中显式赋值：$this->request = $request;，Trait 中再通过 $this->request->get('id') 访问参数。
模型类名不应硬编码在 Trait 中，应通过抽象方法约定：abstract protected function model(): string;，由具体控制器实现并返回 User::class 等字符串，再用 app($this->model()) 实例化——避免静态属性跨请求污染，也防止后期替换模型时要全局搜索替换。
最易忽略的一点：Trait 方法里不要直接调用 json() 或 view() 返回响应，而应只返回数据数组。响应包装交给控制器统一处理，否则调试时难以拦截、日志难打、中间件行为不可控。
