必须显式启用注解扫描，否则@controller完全不生效；需确认安装hyperf/annotation和http-server组件、config/autoload/annotations.php中scan=>true且paths包含控制器目录（如'app/controller'），改后须重启服务并用route:list验证路由注册。
必须显式启用注解扫描，否则 @Controller 完全不生效 —— 这是 90% 新手踩坑的第一步。
为什么加了 @Controller 却 404？
Hyperf 默认关闭注解扫描，@Controller 不是“写了就注册”，而是依赖启动时的静态分析。没开扫描，类和方法上的所有路由注解都会被忽略。
- 确认已安装
hyperf/annotation和hyperf/http-server：运行composer show hyperf/annotation验证 - 打开
config/autoload/annotations.php，确保'scan' => true，且'paths'包含控制器目录，例如：['app/Controller'] - 改完配置后必须重启服务：
php bin/hyperf.php start，热重载不触发注解重新扫描
@Controller 的 prefix 是拼接逻辑，不是路径重写
它只做字符串前缀拼接，不处理斜杠去重、相对路径解析或正则匹配。写错斜杠位置会导致双斜杠（如 /api//users），虽多数情况能被 Swoole 自动归一化，但不可依赖。
- 类上写
#[Controller(prefix: "/api/v1")]，方法写#[GetMapping(path: "users")]→ 实际路由为GET /api/v1/users - 方法 path **不要**以
/开头（即写"users"，而非"/users"），否则可能拼出/api/v1//users - prefix 为空字符串（
""）或不传，等价于无前缀；传null会报错
和 @AutoController 的关键区别在哪？
@AutoController 是“懒人模式”：自动为所有 public 方法生成路由，路径规则固定（/{controller}/{method}）；@Controller + 方法级注解是“精确控制模式”，每个 endpoint 路径、方法、参数注入都可单独定义。
- 用
@AutoController时，无需写@GetMapping等，但无法指定 HTTP 方法（默认 GET/POST）、无法带路径参数、不能复用同一方法响应不同路径 -
@Controller必须配合@GetMapping、@PostMapping等使用，支持path、methods、name等完整参数，也支持@Param、@Query注入 - 二者不能混用在同一类上，否则行为未定义 —— 框架只会识别其中一个
验证是否注册成功最直接的方法
别靠 curl 猜，用内置命令看真实路由表：
- 执行
php bin/hyperf.php route:list，检查输出中是否有你期望的路径、METHOD、HANDLER - 如果没出现，说明注解根本没被扫描到（回看第一个副标题）；如果出现了但访问 404，检查路径大小写、HTTP 方法是否匹配、中间件是否拦截
- 注意：该命令只显示已注册的路由，不校验控制器类是否存在或方法是否可调用 —— 类名写错、方法名拼错，命令里照样显示，但运行时报 500
真正容易被忽略的是：prefix 拼接发生在启动扫描阶段，不是请求时动态计算；而路径参数（如 {id}）的解析和绑定，是运行时由 @Param 或类型提示完成的 —— 这两件事不在同一个生命周期，别指望 prefix 能影响参数提取逻辑。
