新项目无脑用注解路由，老项目或需集中管控时选配置文件路由；注解路由需开启扫描、控制器加@Controller/@AutoController、方法加@GetMapping等注解并重启服务；验证用route:list命令。
Hyperf路由处理新手入门，核心就三点：选对方式、配好开关、验证结果。新项目直接上注解路由，简单清晰；老项目或需统一管控时再考虑配置文件路由。
注解路由怎么快速跑通
写控制器前先确认三件事：
- 已安装 hyperf/http-server 和 hyperf/annotation 组件
-
config/autoload/annotations.php 中
'scan' => true已开启，且'paths'包含app/Controller - 控制器类加了
#[Controller]或#[AutoController]，方法上有#[GetMapping]等注解
例如新建 app/Controller/IndexController.php：
#[Controller(prefix: '/api')]
class IndexController {
#[GetMapping(path: 'health')]
public function health() {
return ['status' => 'up'];
}
}
保存后必须重启服务：php bin/hyperf.php start，否则注解不生效。
配置文件路由什么时候用
不是“过时”，而是承担特定职责：
- 注册全局中间件（如跨域、日志、限流），必须在
Router::group()中声明 - 动态生成路由（比如从数据库读菜单后自动注册）
- 需要正则约束路径，如
/user/{id:\d+}，注解不支持内联正则 - 团队要求所有 API 版本、灰度路径、AB 测试路由集中审计和管理
路由定义写在 config/routes.php，例如：
Router::addGroup('/v1', function () {
Router::get('/users', 'App\Controller\UserController::list');
}, ['middleware' => [CorsMiddleware::class]]);
常见 404 怎么排查
别靠猜，用命令看真实注册结果：
- 运行
php bin/hyperf.php route:list，检查输出里有没有你写的路径、方法和控制器 - 如果没出现 → 注解扫描没开或路径没配对
- 如果出现了但访问 404 → 检查 HTTP 方法是否匹配、URL 大小写、prefix 和 path 斜杠拼接（如
prefix: '/api/'+path: 'users'=/api//users） - 临时重命名控制器文件，再 curl 测试是否返回 404，可反向验证路由归属
@Controller 和 @AutoController 别混用
这是高频翻车点：
-
#[AutoController(prefix: '/api')]：自动把方法名转成路径，如index()→GET /api/index，不支持指定 HTTP 方法或路径参数 -
#[Controller(prefix: '/api/v2')]：必须配合方法级注解，如#[GetMapping(path: 'users')]→ 最终路径是/api/v2/users - 同一个类上同时写两个注解，Hyperf 只认
#[Controller]，#[AutoController]被静默忽略 - prefix 不要以
/结尾，path 也不要以/开头，避免双斜杠
