Hyperf框架快速入门指南：构建高性能HTTP服务

前言

Hyperf是一款基于Swoole扩展的高性能PHP协程框架，专为微服务和中间件开发设计。本文将带您快速了解如何使用Hyperf构建一个基础的HTTP服务，涵盖路由定义、控制器编写、依赖注入等核心功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• PHP 7.4或更高版本
• Swoole 4.5或更高版本
• 已安装Composer包管理工具

路由系统详解

Hyperf提供了灵活的路由定义方式，支持配置文件和注解两种形式。

配置文件路由定义

在config/routes.php中，您可以使用Router类定义路由：

use Hyperf\HttpServer\Router\Router;

// GET请求示例
Router::get('/user', 'App\Controller\UserController::index');

// POST请求示例
Router::post('/user', 'App\Controller\UserController@store');

// 多方法请求示例
Router::addRoute(['GET', 'POST'], '/multi', [\App\Controller\UserController::class, 'multi']);

注解路由定义

Hyperf的注解路由提供了更直观的代码组织方式。

AutoController注解

#[AutoController]是最简单的注解方式，它会自动将类中的public方法映射为路由：

use Hyperf\HttpServer\Annotation\AutoController;

#[AutoController]
class UserController
{
    // 自动映射为GET /user/index
    public function index()
    {
        return 'User List';
    }
}

Controller与RequestMapping注解

对于更精细的控制，可以使用#[Controller]配合#[RequestMapping]：

use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;
use Hyperf\HttpServer\Annotation\PostMapping;

#[Controller(prefix: "/api/user")]
class UserController
{
    #[GetMapping(path: "list")]
    public function list()
    {
        return 'User List';
    }

    #[PostMapping(path: "create")]
    public function create()
    {
        return 'Create User';
    }
}

控制器与请求处理

控制器是处理HTTP请求的核心组件。Hyperf支持传统的MVC模式，也支持更灵活的请求处理器模式。

基础控制器示例

use Hyperf\HttpServer\Contract\RequestInterface;
use Hyperf\HttpServer\Annotation\AutoController;

#[AutoController]
class UserController
{
    public function info(RequestInterface $request)
    {
        $userId = $request->input('id', 0);
        return ['user_id' => $userId];
    }
}

请求对象

Hyperf通过RequestInterface提供了丰富的请求处理方法：

• input() - 获取输入参数
• query() - 获取查询参数
• post() - 获取POST参数
• file() - 获取上传文件
• getHeader() - 获取请求头

依赖注入机制

Hyperf的依赖注入系统是其核心特性之一，提供了强大的解耦能力。

构造函数注入

use App\Service\UserService;

class UserController
{
    private UserService $userService;
    
    public function __construct(UserService $userService)
    {
        $this->userService = $userService;
    }
}

属性注入

use Hyperf\Di\Annotation\Inject;
use App\Service\UserService;

class UserController
{
    #[Inject]
    private UserService $userService;
}

服务启动与管理

启动服务

在项目根目录执行：

php bin/hyperf.php start

服务热重载

由于Hyperf是常驻内存的CLI应用，代码修改后需要重启服务才能生效：

1. 在控制台按CTRL+C停止服务
2. 重新执行启动命令

高级特性：多端口监听

Hyperf支持监听多个端口，适用于API网关等场景：

// config/autoload/server.php
return [
    'servers' => [
        [
            'name' => 'http',
            'type' => Server::SERVER_HTTP,
            'port' => 9501,
            'callbacks' => [
                Event::ON_REQUEST => [Hyperf\HttpServer\Server::class, 'onRequest'],
            ],
        ],
        [
            'name' => 'internal',
            'type' => Server::SERVER_HTTP,
            'port' => 9502,
            'callbacks' => [
                Event::ON_REQUEST => ['InternalHttp', 'onRequest'],
            ],
        ],
    ]
];

对应的路由需要指定server名称：

Router::addServer('internal', function () {
    Router::get('/metrics', 'App\Controller\MetricsController@index');
});

事件系统

Hyperf基于Swoole的事件系统提供了丰富的事件钩子：

事件常量	说明
Event::ON_REQUEST	收到HTTP请求时触发
Event::ON_WORKER_START	Worker进程启动时触发
Event::ON_TASK	任务投递时触发
Event::ON_FINISH	任务完成时触发

结语

通过本文，您已经了解了Hyperf框架的基本使用方法。Hyperf的强大之处远不止于此，它还提供了数据库ORM、缓存、队列、微服务、gRPC等丰富功能，适合构建各种规模的高性能应用。建议继续探索框架的更多特性，以充分发挥其潜力。