Hyperf 3.0 路由注解必须使用 PHP 8 原生 Attributes（如#[Controller(prefix: '/api')]），Doctrine 风格的 @Controller 等注释块已彻底失效且静默不注册；需启用注解扫描、清缓存、确保类名以 Controller 结尾并被 PSR-4 正确加载。
Hyperf 3.0 的路由注解必须用 PHP 8 原生 #[Attribute]，Doctrine 风格的 @Controller 等已彻底失效——不是报错，而是静默不注册路由。
注解语法必须转为 PHP 8 Attributes
v2.2 用的是 Doctrine 注释块，v3.0 全面弃用，连解析器都不加载了。哪怕只漏改一个方法，那个路由就永远 404。
-
/** @Controller(prefix="/api") */→ 必须改为#[Controller(prefix: '/api')] -
/** @GetMapping(path="info") */→ 必须改为#[GetMapping(path: 'info')] -
/** @RequestMapping(methods={"GET"}) */→ 必须改为#[RequestMapping(methods: [RequestMethod::GET])]，且要use HyperfHttpServerAnnotationRequestMethod - 所有注解参数必须用命名参数语法（
prefix:、path:），不能用位置参数或数组字面量
AutoController 和 Controller 行为没变，但写法更严格
#[AutoController] 仍自动挂载 public 方法，#[Controller] 仍需配合 #[GetMapping] 等显式声明——但 v3.0 下，如果类加了 #[Controller] 却没给任何方法加 HTTP 方法注解，Hyperf 不再尝试猜测，而是直接跳过整个类。
-
#[AutoController(prefix: '/v1/user')]：路径生成规则不变（index()→/v1/user/index），但方法必须是public，且不能有同名私有方法干扰扫描 -
#[Controller('/admin')]+#[GetMapping('dashboard')]→ 最终路径是/admin/dashboard，注意斜杠拼接逻辑：类级前缀末尾不带/时，会自动补一个 - 混用
#[Controller]和#[AutoController]在同一个类上，会导致注解冲突，路由注册失败
必须启用注解扫描且清空缓存
v3.0 默认关闭注解扫描，即使语法全对，也不生效。
立即学习“PHP免费学习笔记（深入）”；
- 确认
config/autoload/annotations.php中'scan' => true，且'paths'包含控制器目录（如app/Controller） - 修改注解后，必须执行
php bin/hyperf.php gen:controller或手动删掉runtime/container目录，否则旧路由表仍在内存中 - 检查
composer.json的autoload是否包含"App\": "app/"，否则类根本不会被 Composer 加载，注解自然无效
常见 404 根源：不是写错了，而是没被扫描到
最常被忽略的是「类未被容器识别」这个前提。Hyperf 路由注册发生在 DI 容器构建阶段，如果控制器类没进容器，注解再标准也白搭。
- 控制器类名必须以
Controller结尾（如UserController），否则扫描器直接跳过 - 类必须在
scan.paths指定的目录下，且该目录已在composer.json中配置 PSR-4 自动加载 - 执行
php bin/hyperf.php route:list是唯一验证手段——如果列表里没有你的路由，说明上面任意一环断了 - 别信 IDE 提示：PHPStorm 可能高亮
#[Controller]为合法，但 Hyperf 运行时根本不认，除非你装了对应插件并配置了 Attributes 支持
