Webman使用注解路由_PHP Webman通过注释定义API路径【核心】-php教程-PHP中文网

webman注解路由需依赖第三方扩展（如hg/apidoc），php≥8.0才支持原生属性注解；必须显式安装、启用插件并配置auto_register_routes=true，路径须以/开头，类加#[disabledefaultroute]则方法必须全显式声明。

webman使用注解路由_php webman通过注释定义api路径【核心】

Webman 的注解路由不是框架原生能力，必须依赖第三方扩展（如 hg/apidoc 或 qnnp/webman-route），且 PHP 版本需 ≥ 8.0 才能使用原生属性注解（#[Get]、#[Post] 等）。

注解路由依赖的扩展必须显式安装和配置

Webman 官方不内置注解路由，直接在控制器里写 #[Get] 不会生效。你得先选一个扩展并完成两件事：

执行 composer require hg/apidoc（推荐，生态更全）或 composer require qnnp/webman-route（轻量但已停止维护）
在 config/plugin/ 下启用对应插件配置文件，比如 hg/apidoc 需要确保 config/plugin/hg/apidoc/app.php 中 'enable' => true
确认项目已加载注解解析器：hg/apidoc 依赖 doctrine/annotations，安装时会自动带入；若手动删过依赖，需补上 composer require doctrine/annotations

`#[Get]`、`#[Post]` 这类注解只在方法或类上生效，且路径必须以 `/` 开头

常见错误是把注解当普通注释写，或者路径漏掉斜杠：

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

✅ 正确写法：#[Get('/api/users')]、#[Post('/v1/login')]
❌ 错误写法：#[Get('api/users')]（缺开头 /）、#[Get]（无参数，仅限限制方法，不注册新路由）
⚠️ 注意：如果类上加了 #[DisableDefaultRoute]，那该控制器所有方法都必须显式用注解声明路径，否则 404
多个注解可叠加，比如 #[Get] + #[Post] 表示允许两种方法访问同一路径，但路径仍需至少一个注解提供

注解路由与传统 `Route::get()` 共存时，优先级和调试要点

两者不冲突，但行为逻辑不同，容易混淆：

注解路由在请求进入时由插件中间件动态解析（hg/apidoc 在 support/Bootstrap.php 注册了路由发现机制），而 Route::get() 是启动时静态注册
调试时若发现注解没生效，先检查 var_dump(\hg\apidoc\RouteCollector::collect()) 是否返回预期路由数组；再确认请求 URL 是否匹配注解中写的完整路径（包括前缀）
不要在同一个控制器里混用「注解定义路径」和「默认路由规则」，比如控制器叫 UserController，又写了 #[Get('/user')]，还指望 /user/index 能通过默认规则访问——#[DisableDefaultRoute] 没开的话，后者仍存在，但语义混乱，建议统一风格
hg/apidoc 默认不自动注册路由到 Webman 的 Route 实例，需开启配置项 'auto_register_routes' => true，否则注解只用于生成文档，不参与实际分发

PHP 8 属性注解 vs PHP 7 注释风格注解，兼容性差异明显

如果你还在用 PHP 7.x，#[Get] 类语法会直接报错，只能退回到注释风格（如 /** @Get("/api/user") */），但支持度取决于扩展版本：

hg/apidoc v2.2.0+ 同时支持两种写法，但推荐统一用 PHP 8 属性，更安全、IDE 更易识别
注释风格要求严格格式：/** @Get("/xxx") */ 必须顶格、紧贴方法，不能换行，且不能与其他 DocBlock 混用（比如和 @param 写在一起可能被跳过）
PHP 8 属性注解可放在方法上方任意空白行，也支持重复使用（如同时加 #[Get] 和 #[Apidoc\Url]），但需确保 use 语句引入正确命名空间

最常被忽略的一点：注解路由的中间件绑定不像 Route::get()->middleware() 那样直观，hg/apidoc 通过控制器类上的 #[Middleware] 或方法级注解控制，不是所有中间件都能无缝透传，尤其是自定义全局中间件，务必在测试请求中验证 $request 是否已被处理。