Hyperf注解路由需满足扫描、声明、注册三步才生效：启用config/autoload/annotations.php中'scan'=>true并配置控制器路径；控制器类添加@Controller或@AutoController；方法使用@GetMapping等注解绑定路径与方法。
Hyperf 注解路由不是“写完注解就生效”，必须满足扫描、声明、注册三个环节，缺一不可。最常见问题是写了 #[GetMapping] 却 404，其实路由压根没进系统。
启用注解扫描
这是前提，不开启，所有注解都无效：
- 确认已安装
hyperf/annotation和hyperf/http-server（运行composer show hyperf/annotation验证） - 打开
config/autoload/annotations.php，确保'scan' => true -
'paths'必须显式包含控制器目录，例如：['app/Controller']；若用app/Http/Controllers，就得写全路径 - 路径末尾不加斜杠，也不支持通配符（
app/Controller/**无效） - 改完配置后，清空
runtime/container和runtime/cache目录，并重启服务（php bin/hyperf.php start）
控制器类加注解声明
仅方法上写 #[GetMapping] 没用——Hyperf 先得识别出“这是一个控制器类”，才会去扫描它的方法：
在SEO发布前，从路由清单生成XML网站地图和robots.txt
下载
当代理已经知道网站路由或内容URL，并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时，请使用sitemap。这是一个发布构件技能，而不是爬虫或SEO平台。
- 用
#[Controller(prefix: '/api')]：适合统一前缀、多方法共用中间件的场景；类内所有方法路径自动拼接该前缀 - 用
#[AutoController(prefix: 'user')]：更轻量，自动把 public 方法名转为小写+下划线路径（如getUserInfo→/user/get_user_info），但只支持 GET/POST - 两类注解都要求：类放在扫描路径下（如
app/Controller），且命名空间与目录结构一致（如App\Controller\UserController） - 不能在一个类上同时加
#[Controller]和#[AutoController]，否则行为未定义，框架只认其中一个
方法上绑定 HTTP 路由
方法注解负责具体路径和方法绑定，但要注意拼接逻辑和参数提取方式：
-
#[GetMapping(path: 'users')]中的path是拼接用的，不要以/开头（写"users"，别写"/users"），否则可能拼出双斜杠（如/api//users） - 路径参数如
{id}属于 URL 路径段，需配合#[Param('id')]或类型提示（如int $id）才能注入 - 查询参数（
?page=1&size=10）用#[Query]或$request->query()，不能混用#[Param] - JSON Body 默认不解析，
#[PostMapping]需加#[Body]注解，或手动读取$request->getBody()->getContents() - PHP 8 Attributes 写法是
#[GetMapping(path: '/users')]；旧式 PHPDoc（/** @GetMapping() */）在新版本中弱化支持，IDE 补全差、反射慢
验证是否真正注册成功
别靠 curl 猜，直接看最终生效的路由表：
- 执行
php bin/hyperf.php route:list - 检查输出中是否有你期望的 METHOD、PATH、HANDLER
- 如果没出现，90% 是扫描路径错、注解没生效、或命名空间/目录不匹配（比如类在
App\Controllers，但扫描的是App\Controller） - 如果出现了但访问 404，检查路径大小写、HTTP 方法是否匹配、中间件是否拦截
