医臻链 - 博客

打破偏见：用现代 PHP 姿势解锁 Hyperf 真正实力

2026-01-05 472 0

引言：PHP 真的“不行”吗？每当聊起 PHP，总有人露出一副“懂行”的表情：“这语言上限太低，写出来的代码全是乱麻。”

慢着。你骂的真的是 PHP 吗？ 还是说，你只是在为那些“无分层、无测试、上线即跑路”的代码找替罪羊？

今天，我们以 Hyperf 框架下的“用户注册”功能为例，看看“脚本小子”与“专业开发者”的代码差距究竟在哪里。

一、 警惕：毁掉 Hyperf 的“面条式”写法

很多人把 Hyperf 当成带协程的 index.php。在他们手里，控制器（Controller）变成了逻辑垃圾场：

// ❌ 典型反模式：控制器塞满逻辑
class AuthController extends AbstractController {
    public function register() {
        $email = $this->request->input('email');
        $password = $this->request->input('password');

        // 验证、查库、哈希、发邮件、角色分配... 全部堆在这里
        // 甚至直接用 DB::select("SELECT * FROM users WHERE email = '$email'") 拼 SQL
        // 报错直接 throw，前端直接收 500 Internal Server Error
    }
}

能跑吗？能。可维护吗？零。 Hyperf 的核心是 DI（依赖注入）和 AOP（切面编程），它的设计哲学是鼓励解耦。

二、 现代方案：基于整洁架构的五步重构

我们要构建的不仅是功能，而是一个分层明确、职责单一的系统。

Step 1: 数据载体——定义 DTO

不要在层与层之间传递散乱的 array。使用 DTO（Data Transfer Object）确保类型安全。

namespace App\Dto;

useHyperf\Contract\Arrayable;
useHyperf\Context\Context;

/**
 * 使用 Hyperf 3.1+ 的 Data 属性实现自动映射与验证
 */
#[\Hyperf\Data\Attributes\Data]
class RegisterUserDto implements Arrayable {
    publicfunction __construct(
        public string $email,
        public string $password
    ) {}

    publicstaticfunction fromRequest(array $data): self {
        returnnewself(
            email: trim($data['email'] ?? ''),
            password: (string)($data['password'] ?? '')
        );
    }

    publicfunction toArray(): array {
        return ['email' => $this->email, 'password' => $this->password];
    }
}

Step 2: 领域异常——让错误语义化

别再让前端去猜 500 错误了。定义具体的领域异常，配合 Hyperf 的全局异常处理器（ExceptionHandler）使用。

namespace App\Exception\Domain;

use Hyperf\Server\Exception\ServerException;

class EmailAlreadyTakenException extends ServerException {
    protected $code = 400;
    protected $message = '该邮箱已被注册';
}

Step 3: 数据持久层——Repository 模式

Repository 负责屏蔽数据库细节。未来无论你换成数据库还是缓存，Service 层都不需要改动。

interface UserRepositoryInterface {
    publicfunction existsByEmail(string $email): bool;
    publicfunction create(array $attributes): User;
}

class UserRepository implements UserRepositoryInterface {
    publicfunction existsByEmail(string $email): bool {
        return User::where('email', $email)->exists();
    }

    publicfunction create(array $attributes): User {
        return User::create($attributes);
    }
}

Step 4: 核心业务——Service 逻辑编排

这是最关键的一步：Service 只关心业务逻辑，不关心 Request，也不关心 Response。

namespace App\Service\User;

useApp\Dto\RegisterUserDto;
useApp\Exception\Domain\{EmailAlreadyTakenException, InvalidEmailException};
useApp\Repository\User\UserRepositoryInterface;
useHyperf\Di\Annotation\Inject;
usePsr\EventDispatcher\EventDispatcherInterface;

class RegisterUserService {
    #[Inject]
    protected UserRepositoryInterface $userRepository;

    #[Inject]
    protected EventDispatcherInterface $eventDispatcher;

    publicfunction handle(RegisterUserDto $dto): array {
        // 1. 业务规则校验
        if (!filter_var($dto->email, FILTER_VALIDATE_EMAIL)) thrownew InvalidEmailException();
        if ($this->userRepository->existsByEmail($dto->email)) thrownew EmailAlreadyTakenException();

        // 2. 执行核心动作
        $user = $this->userRepository->create([
            'email' => $dto->email,
            'password' => password_hash($dto->password, PASSWORD_ARGON2ID),
        ]);

        // 3. 异步解耦：触发事件（如发送欢迎邮件）
        $this->eventDispatcher->dispatch(new UserRegistered($user));

        return ['user_id' => $user->id];
    }
}

Step 5: 控制器——薄如蝉翼的胶水层

现在的 Controller 只负责：接收参数 -> 调用服务 -> 返回响应。

#[Controller(prefix: 'auth')]
class AuthController extends AbstractController {
    #[Inject]
    protected RegisterUserService $registerService;

    #[Post('/register')]
    publicfunction register(): ResponseInterface {
        $dto = RegisterUserDto::fromRequest($this->request->all());
        $result = $this->registerService->handle($dto);

        return$this->response->json([
            'status' => 'success',
            'data' => $result
        ]);
    }
}

三、 维度提升：为业务编写单元测试

既然解耦了，测试就变得极其简单。Hyperf 的 Hyperf\Testing 允许你在不启动 Swoole 的情况下秒级完成测试。

public function testRegisterSuccess() {
    // Mock 掉数据库依赖
    $repo = m::mock(UserRepositoryInterface::class);
    $repo->shouldReceive('existsByEmail')->andReturn(false);
    $repo->shouldReceive('create')->once()->andReturn((object)['id' => 99]);

    $this->getContainer()->set(UserRepositoryInterface::class, $repo);

    $service = $this->getContainer()->get(RegisterUserService::class);
    $result = $service->handle(new RegisterUserDto('test@me.com', '12345678'));

    $this->assertEquals(99, $result['user_id']);
}

结语：架构决定上限

Hyperf 提供了协程、DI、注解等强大的“武器”，但它不会阻止你把代码写成一团乱麻。

性能上去了，不代表可维护性可以掉进沟里。 下次听到有人说“PHP 乱”时，你可以把这段代码发给他，然后问他：

“是你写的乱，还是你根本没用现代 PHP 的方式去思考？”

毕竟，代码质量的锅，语言不背，框架也不背。

针对这段架构的 ExceptionHandler（异常处理器）代码示例

既然架构已经分层，那么全局异常处理器（Exception Handler）就是实现“优雅返回”的最后一块拼图。

在现代 PHP 开发中，我们不应该在 Controller 里写满 try-catch。相反，我们应该让异常自然抛出，由专门的 Handler 捕捉并统一格式化。

核心逻辑：异常处理流向图

第一步：定义基础异常类

建议为业务定义一个基类，方便统一拦截处理。

namespace App\Exception;

useHyperf\Server\Exception\ServerException;
useThrowable;

/**
 * 业务异常基类
 */
abstractclass BusinessException extends ServerException
{
    publicfunction __construct(string $message = "", int $code = 400, ?Throwable $previous = null)
    {
        parent::__construct($message, $code, $previous);
    }
}
第二步：编写全局异常处理器

在 app/Exception/Handler 目录下创建 AppExceptionHandler.php。它会捕获所有未被处理的异常。

namespace App\Exception\Handler;

useApp\Exception\BusinessException;
useHyperf\Contract\StdoutLoggerInterface;
useHyperf\ExceptionHandler\ExceptionHandler;
useHyperf\HttpMessage\Stream\SwooleStream;
usePsr\Http\Message\ResponseInterface;
useThrowable;

class AppExceptionHandler extends ExceptionHandler
{
    publicfunction __construct(protected StdoutLoggerInterface $logger) {}

    publicfunction handle(Throwable $throwable, ResponseInterface $response)
    {
        // 1. 处理自定义的业务异常 (如：邮箱已存在、密码太弱)
        if ($throwable instanceof BusinessException) {
            // 阻止异常继续向上传递
            $this->stopPropagation();
            return$this->formatResponse($response, $throwable->getMessage(), $throwable->getCode());
        }

        // 2. 处理系统级异常 (如：代码 Bug、数据库连接断开)
        $this->logger->error(sprintf('%s[%s] in %s', $throwable->getMessage(), $throwable->getLine(), $throwable->getFile()));
        $this->logger->error($throwable->getTraceAsString());

        return$this->formatResponse($response, 'Internal Server Error', 500);
    }

    /**
     * 判断该处理器是否处理此异常
     */
    publicfunction isValid(Throwable $throwable): bool
    {
        returntrue;
    }

    protectedfunction formatResponse(ResponseInterface $response, string $msg, int $code): ResponseInterface
    {
        $data = json_encode([
            'ok'    => false,
            'code'  => $code,
            'error' => $msg,
        ], JSON_UNESCAPED_UNICODE);

        return $response->withHeader('Content-Type', 'application/json')
                        ->withStatus($code === 500 ? 500 : 200) // 业务错误通常返回 200 或 4xx
                        ->withBody(new SwooleStream($data));
    }
}
第三步：在配置中启用

打开 config/autoload/exceptions.php，将你的处理器放到最前面：

return [
    'handler' => [
        'http' => [
            App\Exception\Handler\AppExceptionHandler::class, // 放在第一位
        ],
    ],
];
带来的改变

重构后，你的 Controller 将会变得无比干净，甚至连 try-catch 都不需要：

// 现在的 AuthController
public function register(): ResponseInterface 
{
    $dto = RegisterUserDto::fromRequest($this->request->all());

    // 如果 Service 内部抛出 EmailAlreadyTakenException (继承自 BusinessException)
    // 异常会自动跳过后续代码，被 AppExceptionHandler 捕获并返回标准的 JSON
    $result = $this->registerService->handle($dto);

    return $this->response->json(['ok' => true, 'data' => $result]);
}

总结

这就是现代 PHP 的“整洁之道”：

  1. DTO 保证数据准入；
  2. Service 专注于纯粹的业务逻辑；
  3. Exception Handler 统一收尾。

这样写出来的 PHP 代码，谁还敢说它“乱”？

如何配置 Hyperf 的 Event 监听器，实现注册后自动异步发邮件的逻辑？

在传统的 PHP 脚本里，注册完用户接着写 sendMail()，如果邮件服务器卡了 5 秒，用户就会在注册页面转 5 秒圈圈。但在 Hyperf 中，我们利用 EventDispatcher 结合 协程 或 投递到异步队列，可以让用户瞬间收到“注册成功”的响应，而邮件在后台慢慢发。

以下是实现“注册成功 -> 自动发邮件”的优雅姿势：

第一步：定义事件 (Event)

事件只是一个简单的“传声筒”，用来携带业务数据。

namespace App\Event;

use App\Model\User;

/**
 * 用户注册成功事件
 */
class UserRegistered
{
    public function __construct(public User $user) {}
}

第二步：编写监听器 (Listener)

监听器负责具体的“杂活”（发邮件、发短信、送积分）。

namespace App\Listener;

useApp\Event\UserRegistered;
useHyperf\Event\Annotation\Listener;
useHyperf\Event\Contract\ListenerInterface;
useHyperf\Contract\StdoutLoggerInterface;
useHyperf\Di\Annotation\Inject;

#[Listener]
class SendWelcomeMailListener implements ListenerInterface
{
    #[Inject]
    protected StdoutLoggerInterface $logger;

    publicfunction listen(): array
    {
        // 声明监听哪些事件
        return [
            UserRegistered::class,
        ];
    }

    /**
     * @param UserRegistered $event
     */
    publicfunction process(object $event): void
    {
        $user = $event->user;

        // 模拟发邮件逻辑
        $this->logger->info("正在向 {$user->email} 发送欢迎邮件...");

        // 建议：此处可以用 co::sleep(1) 模拟耗时，或者投递到异步队列
        // 在 Hyperf 中，监听器默认在当前协程执行，
        // 如果想完全不阻塞主流程，可以配合注解或异步队列组件使用
    }
}

第三步：触发事件

回到我们之前的 RegisterUserService，只需要一行代码即可解耦：

// app/Service/User/RegisterUserService.php

publicfunction handle(RegisterUserDto $dto): array
{
    // ... 前面的校验和创建逻辑 ...

    $user = $this->userRepository->create([
        'email' => $dto->email,
        'password' => password_hash($dto->password, PASSWORD_ARGON2ID),
    ]);

    // 🚀 核心：触发事件，Service 不需要关心后续有多少个动作（发邮件、送礼包等）
    $this->eventDispatcher->dispatch(new UserRegistered($user));

    return ['user_id' => $user->id];
}

架构优势：解耦带来的快感

  1. 开闭原则：如果以后产品经理说“注册成功后还要给用户发 10 块钱优惠券”，你只需要新增一个 Listener 即可，完全不需要修改RegisterUserService 的代码。
  2. 性能优化：你可以轻松地在 Listener 中开启一个新的协程来处理邮件发送，或者配合 hyperf/async-queue 组件将其丢入 Redis 队列，实现真正的异步。
  3. 可测试性：在单元测试中，你可以 Mock 掉 EventDispatcher，确保测试只关注注册逻辑，而不去触发真实的邮件发送。

总结

现在，你的系统已经具备了：

  • DTO：严谨的输入。
  • Service：纯净的业务逻辑。
  • Repository：标准的数据存取。
  • Exception Handler：优雅的错误反馈。
  • Event System：灵活的业务扩展。

这套组合拳打下来，谁还敢说 PHP 只适合写小脚本？这已经是标准的企业级生产架构了。

* 文章转摘自公众号【php的自我修养】文章 别再把代码写烂了，还怪 PHP 不行

Kai Wang的头像 Kai Wang
0 2

相关文章