hyperf 的 @controller 注解需开启注解扫描才生效，仅添加注解不注册路由；必须配置 annotations.php 中 scan=>true 并指定 paths，开发期建议 scan_cacheable=false。
Hyperf 的 @Controller 注解必须配合注解扫描启用才能生效，单独加在类上不会注册任何路由。
必须先开启 annotations.php 中的 scan 配置
Hyperf 默认关闭注解扫描，@Controller 不是“加了就自动注册”的魔法标签。它依赖启动时的静态分析流程。
- 确认已安装
hyperf/annotation和hyperf/http-server - 编辑
config/autoload/annotations.php，确保'scan' => true - 在
'paths'数组中加入控制器目录，例如：app/Controller - 开发阶段建议设
SCAN_CACHEABLE=false（写在.env），否则改了注解不重启也刷不出来
@Controller(prefix: "...") 和 @AutoController 的区别
两者都声明控制器，但语义和行为不同，选错会导致路径意外或 404。
-
@Controller(prefix: "/api")：只声明前缀，**不自动注册方法路由**；必须配合@GetMapping等方法级注解使用 -
@AutoController()：自动为所有 public 方法生成路由，路径规则为/{类名小写}/{方法名}（如IndexController::test→/index/test） -
@AutoController(prefix: "v1")会把前缀加在自动生成的路径最前面，变成/v1/index/test - 别混用：一个类同时加
@Controller和@AutoController会导致扫描冲突，路由可能漏注册
path 参数里不能带开头斜杠
这是高频翻车点。方法注解里的 path 是拼接用的，不是完整 URI。
- 错：
@GetMapping(path: "/users")+@Controller(prefix: "/api")→ 实际注册成/api//users（双斜杠） - 对：
@GetMapping(path: "users")→ 正确拼出/api/users - 带参数也一样：
@GetMapping(path: "users/{id}")，不是/users/{id} - 如果 prefix 是空字符串或没设，
path: "users"就直接注册为/users
中间件和参数注入要配对引入命名空间
注解本身只是标记，背后依赖对应的类加载和解析逻辑，缺命名空间导入就静默失效。
- 用
@Middleware必须use Hyperf\HttpServer\Annotation\Middleware - 用
@Param提取路径参数，得use Hyperf\HttpServer\Annotation\Param - 类型提示注入
RequestInterface $request没问题，但若用@Query("page") int $page，就得确保导入了@Query注解类 - IDE 可能不报错，但运行时参数拿不到、中间件不执行——这类问题只能靠
php bin/hyperf.php route:list对照验证
最常被忽略的是 route:list 命令输出里路径是否符合预期，以及 SCAN_CACHEABLE=false 在开发期的实际作用——缓存不刷新，改了注解等于白改。
