AutoController注解生效需满足硬性条件：必须安装hyperf/http-server组件，控制器置于app/Controller目录且命名空间匹配，使用PHP 8命名参数语法如#[AutoController(prefix: '/api')]，并执行route:list验证注册结果。
AutoController 注解必须配合 hyperf/http-server 才能生效
骨架项目默认不带 HTTP 服务组件，composer create-project hyperf/hyperf-skeleton 后直接 php bin/hyperf.php start 会静默启动但无端口监听，curl 访问超时——这是最常被卡住的第一步。
必须显式安装：composer require hyperf/http-server。这一步不是可选，是硬性依赖。没它，@AutoController 注解会被扫描到，但路由分发器根本不会加载，控制器形同虚设。
- 检查是否装好：运行
php bin/hyperf.php support:list，输出中应含hyperf/http-server - 若用 Docker，确保容器内
php --ri swoole显示 Swoole ≥5.0 且已启用 - PHP 版本必须 ≥8.1，否则注解语法（如
#[AutoController]）直接报错
prefix 参数写法错误会导致全部路由 404
#[AutoController(prefix: '/api')] 是对的；#[AutoController(prefix: '/api/')] 或 #[AutoController(prefix: 'api')] 都会导致路由匹配失败——前者多出结尾 /，FastRoute 解析时无法对齐路径段；后者缺开头 /，被当成相对路径处理。
实际生成的路由是拼接结果：prefix + 方法名小写，例如 index() → /api/index，getUserInfo() → /api/get-user-info（自动转 kebab-case）。
- 方法名含大写字母时，Hyperf 自动转为短横线分隔，不支持下划线命名（
get_user_info不会变成/api/get-user-info） - 如果想禁用自动转换，改用
@Controller+@GetMapping显式声明路径 - prefix 必须是字符串字面量，不能是变量或常量
IDE 提示失效？缺 PHP Annotations 插件
PhpStorm 默认不识别 #[AutoController] 这类 PHP 8+ 属性注解，光装了 hyperf/http-server 还是会标红、无跳转、无补全——这不是代码问题，是 IDE 缺插件。
必须安装官方推荐的 PHP Annotations 插件（JetBrains 插件市场搜这个名字），重启后注解才可点击跳转、悬停提示参数含义。
- 不装该插件，
#[AutoController(prefix: '/api')]在编辑器里只是普通文本，容易手误写成@AutoController（旧式注释风格，已废弃） - 装完插件后，按 Ctrl+Click 可直接跳到
AutoController类定义，方便查源码看支持哪些参数 - 别混淆
Swoole IDE Helper，那是给 Swoole 原生 API 补全用的，和路由注解无关
路由没注册？先跑 route:list 确认扫描结果
写完控制器、启动服务，curl 却返回 404，别急着改代码——先验证框架是否真把路由加载进来了。
执行：php bin/hyperf.php route:list。输出中必须出现类似这一行：
GET | /api/index | App\Controller\IndexController::index
如果没有，说明注解未被扫描，常见原因：
- 控制器文件没放在
app/Controller/目录下（路径不对，扫描器找不到） - 命名空间写成
App\Controllers（少个r）或app\Controller（首字母小写） - 类没加
public方法，只有private或protected——@AutoController只绑定 public 方法 - PHP 缓存未清理：改完注解后执行
php bin/hyperf.php clear:cache再重试
注解路由依赖反射扫描，任何语法错误、路径错误、命名空间错误都会导致整类被跳过，不会报错，只会静默忽略——这点最容易被忽略。
