Hyperf控制器是处理HTTP请求的核心组件，需通过命令创建、注解定义路由、依赖注入调用服务，并遵循只负责请求响应、不写业务逻辑等规范。
Hyperf 控制器是处理 HTTP 请求的核心组件，创建和编写控制器非常简单，关键在于理解其依赖注入机制、路由绑定方式以及与框架其他组件（如中间件、验证器、服务类）的协作逻辑。
一、使用命令行快速创建控制器
Hyperf 提供了 Artisan 风格的命令工具，推荐优先使用命令生成标准结构：
- 运行 php bin/hyperf.php make:controller UserController，会在
app/Controller目录下生成UserController.php - 若需 API 风格控制器（不带视图渲染逻辑），可加
--api参数：php bin/hyperf.php make:controller Api/UserController --api - 生成的控制器默认继承
Hyperf\HttpServer\Controller\AbstractController，已预置$request和$response属性
二、控制器基础结构与关键写法
一个典型控制器需关注命名空间、注解路由、方法返回值及依赖注入方式：
- 控制器类必须放在
App\Controller命名空间下（或按composer.json的 PSR-4 配置自定义） - 使用
@Controller注解声明控制器，配合@GetMapping/@PostMapping等标注具体动作，例如：
#[Controller]
class UserController
{
#[GetMapping("/users/{id}")]
public function view(int $id): array
{
return ['id' => $id, 'name' => 'Hyperf'];
}
} - 方法参数支持自动注入：如
RequestInterface $request、UserService $service，Hyperf 会通过 DI 容器解析
三、常见实用技巧与注意事项
避免踩坑，提升可维护性：
- 不要在控制器中写业务逻辑，只负责接收请求、调用服务层、组装响应；复杂校验建议用
Validation组件或自定义Request类 - 返回值尽量统一：数组自动转 JSON，
Response对象可精细控制状态码和 Header，View对象用于模板渲染（需启用 View 组件） - 若控制器需跨模块复用（如 Admin 和 API 共用逻辑），可抽象为 Trait 或基类，但注意 DI 容器无法自动注入 Trait 中的属性
- 路由参数类型提示（如
int $id）会触发自动类型转换，但失败时抛出BadRequestHttpException，建议搭配异常处理器统一捕获
四、关联路由配置与调试建议
控制器生效依赖正确路由注册，开发阶段建议：
- 确认
config/autoload/routes.php是否启用（默认已加载），无需手动注册注解路由 - 执行 php bin/hyperf.php route:list 查看当前所有注册路由，验证路径、方法、中间件是否匹配预期
- 开启调试模式（
SWOOLE_HTTP_DEBUG=1或配置debug => true）可看到更详细的请求生命周期日志 - 修改控制器后需重启服务（Hyperf 默认不支持热重载控制器文件），可配合
watcher组件实现自动重启
