必须安装hyperf/annotation和hyperf/http-server组件，并在annotations.php中启用scan=>true且正确配置paths路径，否则注解路由不生效。
确认是否已安装必要组件
注解路由不是开箱即用的，必须显式安装 hyperf/annotation 和 hyperf/http-server。缺一不可——前者提供注解解析能力，后者提供 HTTP 路由调度支持。
- 运行
composer show hyperf/annotation和composer show hyperf/http-server确认已安装 - 若未安装，执行
composer require hyperf/annotation hyperf/http-server - 注意：Hyperf 3.x 默认不包含
hyperf/annotation，即使创建项目时选了“完整版”，也需手动装
启用 annotations.php 中的 scan 配置
Hyperf 不会自动扫描注解，必须在 config/autoload/annotations.php 中打开开关并指定路径，否则所有 #[Controller]、#[GetMapping] 都会被忽略。
- 确保该文件中
'scan' => true已设置（不是注释掉） -
'paths'必须包含控制器目录，例如['app/Controller']；如果控制器在app/Http/Controllers，就得写对应路径 - 路径必须是相对于项目根目录的，且不能以
/开头（'/app/Controller'是错的） - 修改后需重启服务（Swoole Worker），仅 reload 不生效
@AutoController 和 @Controller 的选择差异
两者都依赖注解扫描，但行为不同，选错会导致路由注册失败或路径不符合预期。
-
#[AutoController]：按方法名自动生成路由，如index()→/controller-name/index；默认只支持 GET/POST，不支持中间件配置 -
#[Controller]：必须配合#[GetMapping]等方法级注解使用；支持prefix参数，也支持middleware选项（如#[Controller(middleware: [AuthMiddleware::class])]） - 别混用：一个类上同时写
#[AutoController]和#[Controller]会冲突，优先级未定义，实际行为取决于扫描顺序
验证注解是否真正生效
光写注解不等于路由注册成功。常见“写了但 404”问题，往往卡在扫描环节或命名空间错误。
- 执行
php bin/hyperf.php route:list，检查输出中是否出现你期望的路径（如GET /user/info） - 若列表为空，说明扫描没触发——回看
annotations.php的scan和paths - 若路径存在但访问 404，检查控制器类是否用了正确的命名空间（必须是
App\Controller\*或你在paths中声明的命名空间前缀） - PHP 8+ 强烈推荐用 Attributes（
#[GetMapping]），而非 DocBlock（/** @GetMapping */）；后者在 IDE 或反射中容易被忽略，且不支持类型提示校验
注解路由真正的门槛不在语法，而在「扫描是否启动」和「路径是否被纳入扫描范围」——这两点漏掉任何一个，代码写得再标准也没用。
