Webman自动路由需手动启用，有默认映射、auto-route插件、注解路由三种方式；注解路由要求v2.2.0+、命名空间严格匹配、路径以/开头；禁用默认路由并显式声明更安全。
Webman 的自动路由不是“开箱即用”的默认行为，而是需要明确启用或通过插件/注解激活的可选机制；盲目依赖它容易导致路由不可控、调试困难、权限遗漏。
自动路由在 Webman 中实际有三种启用方式
你看到的 http://127.0.0.1:8787/foo/test 能直接访问，并非框架默认打开所有控制器，而是由三类机制之一触发：
- 默认控制器映射（仅限简单结构）：当
config/route.php里没定义任何路由，且 URL 路径符合{控制器}/{动作}规则时，Webman 会尝试自动解析app\controller\FooController::test()—— 但该机制在 v2.2+ 已被弱化，且不支持嵌套命名空间（如admin\v1\controller） - 自动路由插件（
webman/auto-route）：需composer require webman/auto-route安装，它会扫描app/controller/下所有控制器类，为每个 public 方法注册对应路由。它会跳过已手动定义的路由，但不校验方法是否存在中间件或参数类型 - 注解路由（v2.2.0+ 推荐）：在控制器类或方法上加
#[Get]、#[Route]等，框架启动时自动收集。这种方式可控性强，支持路径约束、多方法、路由名，且与手动路由共存无冲突
注解路由必须注意的两个硬性前提
很多人加了 #[Get] 却没生效，往往卡在这两点：
-
webman-framework版本必须 ≥v2.2.0，旧版本不识别 PHP 8.0+ 属性（Attribute）语法，会直接忽略注解 - 控制器类所在命名空间必须能被自动加载器正确解析，比如类文件路径是
app/controller/UserController.php，那么命名空间必须严格为app\controller；若写成App\Controller或漏掉\controller，注解将无法绑定到路由系统 - 注解路径必须以
/开头，例如#[Get('user/{id}')]是无效的，必须写成#[Get('/user/{id}')]
自动路由插件的典型陷阱
webman/auto-route 插件看似省事，但上线后常引发线上问题：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
立即学习“PHP免费学习笔记（深入）”；
- 它会把所有 public 方法（包括
__construct、init、helper这类非动作方法）也注册为可访问路由，造成未授权接口暴露 - 不支持参数约束（如
{id:\d+}），也不支持中间件自动注入，每个需要鉴权或校验的接口仍得额外补中间件配置 - 当项目启用多应用（如
app/admin和app/api）时，插件默认只扫描app/controller，不会递归进子目录，除非你手动改插件配置 - 它和注解路由共存时，优先级规则是“手动路由 > 注解路由 > 自动路由”，但这个顺序不体现在日志或调试面板中，排查冲突时只能靠
php start.php start -d启动后看控制台打印的实际注册列表
真正安全的自动映射实践建议
不要追求“完全零配置”，而应聚焦在“最小必要配置 + 显式控制”：
- 禁用默认路由：在控制器类顶部加
#[DisableDefaultRoute]，强制所有入口必须显式声明，避免意外暴露 - 用
#[RouteGroup('/api/v1')]统一前缀，再配合#[Get('/users')]，比拼接字符串更可靠 - 对敏感操作（如
delete、update）坚持手动配中间件：->middleware(app\middleware\Auth::class)，别指望自动机制覆盖权限逻辑 - 上线前运行
php start.php get-routes（需安装webman/console）导出路由表，人工核对是否有冗余或缺失路径
自动映射最危险的地方，是它让开发者误以为“路由已就绪”，从而跳过对请求方法、参数校验、中间件链、错误响应格式的主动设计。真正的效率提升，来自清晰的约定和可验证的配置，而不是隐藏的魔法。
