Hyperf 2.x 注解路由需手动启用扫描并配置 annotations.php，控制器须用 #[Controller] 标识、方法用 #[GetMapping] 等属性注解，路径参数自动绑定且支持类型提示，PHP 版本须 ≥8.0。
Hyperf 2.x 的注解路由是基于 @Controller 和 @RequestMapping（及其快捷注解如 @GetMapping、@PostMapping 等）实现的，需配合 AOP 和注解扫描机制工作。它不是“开箱即用”的默认行为，必须手动启用注解扫描并确保控制器类被正确加载。
启用注解扫描和路由自动注册
Hyperf 默认不会自动扫描控制器，需要在 config/autoload/annotations.php 中配置扫描路径：
- 确保该文件存在且返回数组，例如：
// config/autoload/annotations.php
return [
'scan' => [
'paths' => [
'app/Controller',
],
'ignore_annotations' => [
'method', 'package'
],
],
];
```
- 同时确认
app/Controller下的类使用了@Controller注解，并继承自Hyperf\HttpServer\Contract\ControllerInterface（通常通过Hyperf\HttpServer\Controller\AbstractController间接实现）； - 若使用自定义命名空间，请确保其包含在
scan.paths中，且 PSR-4 自动加载已配置（检查composer.json的autoload部分）。
编写带注解的控制器
一个标准的注解路由控制器示例如下：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
// app/Controller/UserController.php
namespace App\Controller;
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;
use Hyperf\HttpServer\Annotation\PostMapping;
use Hyperf\HttpServer\Controller\AbstractController;
#[Controller]
class UserController extends AbstractController
{
#[GetMapping("/user/{id}")]
public function view(int $id)
{
return $this->response->json(['id' => $id, 'name' => 'Hyperf']);
}
#[PostMapping("/user")]
public function store()
{
$data = $this->request->all();
return $this->response->json(['status' => 'created', 'data' => $data]);
}
}
```
-
#[Controller]是类级注解，标识该类为控制器； - 方法级注解如
#[GetMapping]会自动注册对应 HTTP 方法 + 路径的路由； - 路径参数（如
{id}）会自动绑定到方法参数，类型提示（int $id）支持自动类型转换与验证（需开启参数验证中间件）； - 注意：Hyperf 2.x 使用 PHP 8+ 属性（Attribute），写法为
#[xxx]，不是 PHP 7 的 DocBlock 注释式注解（如/** @GetMapping */）。
验证路由是否生效
启动服务后，可通过以下方式确认注解路由已加载：
- 执行命令查看当前注册的所有路由：
php bin/hyperf.php route:list—— 若看到/user/{id}和/user条目，说明成功； - 若无输出或报错，检查日志（
runtime/logs/hyperf.log）是否有扫描失败、类未找到或注解解析异常； - 常见问题包括：PHP 版本低于 8.0（不支持 Attribute）、注解拼写错误（如写成
@GetMapping而非#[GetMapping]）、控制器未加#[Controller]、或annotations.php配置未生效（如文件名错误或返回非数组）。
进阶：组合注解与分组前缀
可使用 #[AutoController] 快速生成 RESTful 路由，或通过 #[Controller(prefix: "/api/v1/user")] 统一添加前缀：
#[Controller(prefix: "/api/v1/user")]
class UserController extends AbstractController
{
#[GetMapping("/{id}")] // 实际匹配 /api/v1/user/{id}
public function view($id) { ... }
}
```
-
prefix支持嵌套，方法级注解路径会自动拼接； - 若需对某控制器统一加中间件，可用
#[Middleware(AuthMiddleware::class)]类级注解； - 多个注解可叠加，如
#[GetMapping("/list"), Middleware(PaginationMiddleware::class)]。
