hyperf注解路由必须满足扫描、声明、注册三步才生效：启用config/autoload/annotations.php中'scan'=>true并配置正确paths；控制器类加@controller或@autocontroller；方法用@getmapping等注解绑定路径。
Hyperf 注解路由不是“加了注解就自动生效”，必须满足扫描、声明、注册三个环节，缺一不可。否则 route:list 里根本看不到你的路由，访问直接 404。
开启注解扫描是前提
Hyperf 默认不扫描任何注解。必须确认以下三点都到位：
- 项目已安装
hyperf/annotation和hyperf/http-server（运行composer show hyperf/annotation验证） -
config/autoload/annotations.php中'scan' => true已启用 -
'paths'明确包含控制器目录，例如['app/Controller']；若用app/Http/Controllers，就得写全路径，不能省略 - 开发阶段建议在
.env中设置SCAN_CACHEABLE=false，避免改了注解却没刷新缓存 - 修改配置后必须重启服务：
php bin/hyperf.php start，热重载不触发注解重新扫描
控制器类要正确声明
仅在方法上写 #[GetMapping] 没用——Hyperf 先得识别出“这是个控制器”，才会去解析它的方法。
- 使用
#[Controller(prefix: '/api')]：适合统一前缀、需精细控制每个接口的场景；所有方法路由会自动拼上前缀 - 使用
#[AutoController(prefix: 'v1')]：自动为 public 方法生成路径，如UserController::listUsers()→/v1/user/list_users；但只支持 GET/POST，不支持路径参数或自定义方法 - 二者不能混用在同一类上，否则行为未定义
- 类必须放在扫描路径下，且命名空间与目录结构严格一致（如
app/Controller/UserController.php对应App\Controller\UserController）
方法注解要写对格式和参数
路径拼接有规则，参数提取靠显式声明，不是自动推断。
- 方法级注解的
path不要以/开头，例如写path: "users"，不是path: "/users"；否则和类前缀拼出/api//users - 路径参数如
users/{id}，需配合#[Param('id')]或类型提示int $id才能注入 - 查询参数（
?page=1&size=10）用#[Query]，请求体 JSON 用#[Body]，不能混用 - PHP 8 Attributes 写法为
#[GetMapping(path: 'users')]；旧式 PHPDoc 注解（/** @GetMapping() */）已弱化支持，补全差、反射慢 - 每个注解类都要手动
use，比如use Hyperf\HttpServer\Annotation\Param;，漏了就静默失效
验证是否真正注册成功
别靠 curl 猜，直接看路由表：
- 执行
php bin/hyperf.php route:list - 检查输出中是否有对应 METHOD、PATH、HANDLER（如
GET | /api/users | App\Controller\UserController::list） - 如果没出现，90% 是扫描路径错、注解没加载、或命名空间不匹配
- 如果出现了但访问 404，检查大小写、HTTP 方法是否一致、中间件是否拦截、以及
onHandShake是否放行该路径（WebSocket 场景）
