3.0 升級指南

3.0 版本主要修改了 PHP 最低版本為 8.0
框架移除了 Doctrine Annotations，改成使用 PHP8 Attributes
框架增加了大量的成員變量類型限制

轉化所有註解為原生註解

注意: 這個步驟只能在 2.2 版本下執行

以下腳本會將所有 Doctrine Annotations 轉化為 PHP8 Attributes。

composer require hyperf/code-generator
php bin/hyperf.php code:generate -D app

修改 Hyperf 組件版本

直接將 composer.json 中的 hyperf/* 統一修改為 3.0.* 即可。

hyperf/engine 不跟隨框架版本號，故不需要修改，確保為 ^2.1.0 版本即可，如果使用的 Hyperf 版本低於 v3.0，則需要使用 ^1.5 版本的 engine 組件。

後面只需要執行 composer update -o，就可以正常完成升級了。

升級數據庫模型類

因為模型基類增加了成員變量的類型支持，所以需要使用以下腳本，將其升級為新版本。

composer require hyperf/code-generator
php vendor/bin/regenerate-models.php $PWD/app/Model

Logger

monolog/monolog 3.x 版本因為使用了 PHP8.1 的新特性，所以需要對某些類進行特殊修改

將 array $record 修改為 array|LogRecord $record 即可兼容 3.x 版本，示例代碼如下

<?php

declare(strict_types=1);

namespace App\Kernel\Log;

use Hyperf\Context\Context;
use Hyperf\Coroutine\Coroutine;
use Monolog\LogRecord;
use Monolog\Processor\ProcessorInterface;

class AppendRequestIdProcessor implements ProcessorInterface
{
    public const REQUEST_ID = 'log.request.id';

    public function __invoke(array|LogRecord $record)
    {
        $record['extra']['request_id'] = Context::getOrSet(self::REQUEST_ID, uniqid());
        $record['extra']['coroutine_id'] = Coroutine::id();
        return $record;
    }
}

Command

3.0 版本後，命令行默認開啓了事件監聽器，所以當有監聽器監聽了 Command 的事件，且進行了 AMQP 或者其他多路複用的邏輯後，會導致進程無法退出。

解決辦法

方法一：

執行命令時，增加選項 --disable-event-dispatcher

方法二：

增加監聽器

<?php

declare(strict_types=1);

namespace App\Listener;

use Hyperf\Command\Event\AfterExecute;
use Hyperf\Coordinator\Constants;
use Hyperf\Coordinator\CoordinatorManager;
use Hyperf\Event\Annotation\Listener;
use Hyperf\Event\Contract\ListenerInterface;

#[Listener]
class ResumeExitCoordinatorListener implements ListenerInterface
{
    public function listen(): array
    {
        return [
            AfterExecute::class,
        ];
    }

    public function process(object $event): void
    {
        CoordinatorManager::until(Constants::WORKER_EXIT)->resume();
    }
}

替換 Hyperf\Utils\Context

由於 3.0 的 Context 換了命名空間 , 得全局替換 Hyperf\Utils\Context => Hyperf\Context\Context。

啓動服務

接下來只需要啓動服務，就可以看到不適配的地方，逐一修改即可。

AMQP Consumer 和 Producer 成員變量增加了類型
Listener 監聽器的 process 方法增加了 void 返回值類型
註解 CircuitBreaker 將 $timeout 參數改為了 $options.timeout
異步隊列 Async Queue 的成員變量增加了類型
異步隊列，event->message 字段修改為非 public 類型，需要使用 event->getMessage() 讀取。

gRPC

框架根據 gRPC 規範修改了 gRPC Server 返回的 Http status 固定為為 200， gRPC Server 返回對應的 status code，更新前如果有使用 gRPC，請務必將相關的服務升級到 3.x 版本，不然會導致請求出現異常時，對端無法正常解析錯誤。

3.7 KiB Raw Blame History Unescape Escape