Hyperf v3.2 升级指南:破坏性变更、配置迁移与新增能力全解析

原创2026-10-09 12:22:201,612 阅读
文章标签:后端微服务

Hyperf v3.2 升级指南:破坏性变更、配置迁移与新增能力全解析

Hyperf v3.2 是 3.x 系列的一次重要迭代(首个版本 v3.2.0 于 2026-06-07 发布,随后通过 v3.2.1、v3.2.2、v3.2.3、v3.2.4 持续修补),其核心工作集中在三方面:一是对 logger、cache、async-queue 等组件配置结构进行标准化重构(包含破坏性变更);二是针对 PHP 8.4、elasticsearch 8/9.x、Carbon v3 等上游生态做兼容升级;三是清理了大量历史废弃代码。本文以仓库内 docs/zh-hk/changelog/3.2.md 为骨架,结合源码实现逐项展开,帮助你在升级到 v3.2 时准确完成配置迁移、规避行为变化带来的坑,并第一时间用上新增能力。

一、版本线概览:v3.2.0 → v3.2.4

版本 发布日期 主要内容
v3.2.0 2026-06-07 破坏性变更(Carbon、async-queue、logger、cache、swow)、依赖升级、大批废弃代码移除、新增能力集中落地
v3.2.1 2026-06-15 修复 gen:model 继承重写、新增无 set_error_handler 的 StreamHandler、优化 Timer::tick() 协程上下文
v3.2.2 2026-07-26 移除第二批废弃代码、修复多项验证/迁移/扫描/预加载缺陷
v3.2.3 2026-07-29 新增 existent() 函数、修复模型 @property 类型标注与 phpdoc
v3.2.4 2026-08-10 新增 assert_instanceof()、Nacos 多版本实例主机读取、日志目录竞态修复

整体升级建议:先处理下面的破坏性变更,再逐步跟进补丁版本。

二、破坏性变更(升级必读)

1. Carbon 组件行为变更

  • Carbon::createFromTimestamp() 在 v3.2(配合 Carbon v3.0)中不再通过 date_default_timezone_get() 读取默认时区,使用方式需要显式传入时区参数。
  • Carbon::diffInDays() 默认不再返回绝对值,如需绝对值必须显式传入 $absolute 参数。
<?php

use Carbon\Carbon;

$t = time();

// 不兼容的用法(依赖默认时区读取)
Carbon::createFromTimestamp($t, date_default_timezone_get());

// 正确的用法(显式指定时区)
Carbon::createFromTimestamp($t, date_default_timezone_get());

diffInDays() 的语义变化尤其容易在“计算两个日期相差几天”的业务中出现符号反转,升级后建议自查所有调用点,按需补上 $absolute = true。

2. async-queue:getQueueName() 重命名为 getPoolName()

为了术语一致性(队列实例在实现上对应“连接池 pool”),JobInterface::getQueueName() 被重命名为 getPoolName()。源码层面,接口定义与默认实现均已切换为新名称:

因此所有自定义 Job 需要同步迁移:

<?php
// 变更前
class CustomJob extends \Hyperf\AsyncQueue\Job
{
    public function getQueueName(): string
    {
        return 'custom';
    }
}

// 变更后
class CustomJob extends \Hyperf\AsyncQueue\Job
{
    public function getPoolName(): string
    {
        return 'custom';
    }
}

配套变更:ConsumerProcess 的 $queue 属性也重命名为 $pool(对应 src/async-queue/src/Process/ConsumerProcess.php),进程名由 queue.{$pool} 生成。

3. logger 配置结构变更

旧结构是“default 直接承载驱动配置”,新结构引入了 channels 分层:顶层 default 只存放默认 channel 名称字符串,具体配置下沉到 channels 下。变更细节见 src/logger/publish/logger.php 与 src/logger/src/LoggerFactory.php。

<?php

// 变更前
return [
    'default' => [
        'driver' => 'daily',
        'path' => BASE_PATH . '/runtime/logs/hyperf.log',
        'level' => env('LOG_LEVEL', 'debug'),
        'days' => 7,
    ],
];

// 变更后
return [
    'default' => 'default',
    'channels' => [
        'default' => [
            'driver' => 'daily',
            'path' => BASE_PATH . '/runtime/logs/hyperf.log',
            'level' => env('LOG_LEVEL', 'debug'),
            'days' => 7,
        ],
        // 在此处添加你自定义的 channel
    ],
];

从源码看,LoggerFactory 构造函数 对旧式配置做了兼容兜底(检测到缺少 logger.channels 或 logger.default 仍是数组时自动包装为 ['default' => 'default', 'channels' => 旧配置]),make()/get() 均按 logger.channels.{channel} 读取。升级后建议立即改用新结构,以获得多 channel 命名与独立 handler/formatter 组合能力——官方发布配置中已经预置 stack、single、daily、stderr、syslog、null 六个 channel 模板。

4. cache 配置结构变更

与 logger 同步,cache 配置改为 stores 多存储结构:顶层 default 用 env('CACHE_DRIVER', 'default') 指定默认存储名,各存储配置下沉到 stores。官方发布配置见 src/cache/publish/cache.php。

<?php
// 变更前
return [
    'default' => [
        'driver' => RedisDriver::class,
        'packer' => PhpSerializerPacker::class,
        'prefix' => 'c:',
    ],
];

// 变更后
return [
    'default' => env('CACHE_DRIVER', 'default'),
    'stores' => [
        'default' => [
            'driver' => RedisDriver::class,
            'packer' => PhpSerializerPacker::class,
            'prefix' => 'c:',
        ],
    ],
];

注意发布配置中 default store 还包含 skip_cache_results 与 options.pool 等字段,其中 options.pool 指向 Redis 连接池名称(默认 'default')。CacheManager 同样内置了对旧配置的兼容判断(当 cache.stores 不存在或 cache.default 为数组时自动转换),但推荐按新结构显式迁移。

5. 使用 swow 驱动时需要新增依赖绑定

如果使用 Swow 引擎,需要在 config/autoload/dependencies.php 中显式声明响应发射器实现:

<?php
use Hyperf\Contract\ResponseEmitterInterface;
use Hyperf\Engine\ResponseEmitter;

return [
    ResponseEmitterInterface::class => ResponseEmitter::class,
];

这一变更意味着从 v3.2 起,框架不再隐式绑定 Swow 场景下的响应发射器,升级到 Swow 运行环境时必须补齐上述映射。

三、PHP 8.4 注意事项:fgetcsv / fputcsv 的 escape 参数

如果你已将运行时升级到 PHP 8.4,fgetcsv 与 fputcsv 现在要求为 escape 参数提供默认值,否则会抛出弃用警告甚至报错。涉及 CSV 读写的位置必须显式传 escape: '':

fputcsv($fp, $fields) 必须修改为 fputcsv($fp, $fields, escape: '')
fgetcsv($fp) 必须修改为 fgetcsv($fp, escape: '')

与之呼应,v3.2 中 str_getcsv 的内部实现也已改为使用空字符串作为 escape(见“行为变更”章节),保证 CSV 解析行为在 PHP 8.4 下保持一致。

四、依赖升级清单

v3.2 对运行环境与关键依赖提出了新的版本要求,升级前请先核对 composer 约束:

  • PHP 版本升级至 >=8.2
  • elasticsearch/elasticsearch 升级至 ^8.0 || ^9.0
  • nikic/php-parser 升级至 5.6
  • symfony/* 组件升级至 ^6.0 || ^7.0
  • phpunit/phpunit 升级至 ^11.0
  • google/protobuf 升级至 ^3.6.1 || ^4.2
  • guzzlehttp/guzzle 升级至 ^7.0
  • nesbot/carbon 支持 v3.0(与上述 Carbon 行为变更配套)
  • Monolog 不再支持 2.x,仅支持 3.x(对应 src/logger/publish/logger.php 中 Monolog\Level 等 3.x API 的使用)

五、移除的废弃代码(Removed)

v3.2 集中清理了历史欠账,升级后若仍引用以下符号会直接报错,需提前替换:

  • 移除废弃的 laminas/laminas-mime 包。
  • 移除废弃的 Hyperf\Serializer\Contract\CacheableSupportsMethodInterface 接口。
  • 移除 Hyperf\AsyncQueue\JobMessage 序列化中的向后兼容代码。
  • 按计划移除的废弃代码:Collection 向后兼容代码、ProxyTrait 参数映射、ResumeExitCoordinatorListener、SocketIO Future 的 flag 参数、WebSocket HandeShakeException 拼写错误别名(正确拼写为 HandShakeException)。
  • v3.2.2 追加移除:ConsumerProcess::$queue 向后兼容支持(改用 $pool)、forceIndexes()(改用 forceIndex())、str_replace_once()(改用 strReplaceOnce())、ClassLoader::loadDotenv()、GrpcClient::hanldeNaming()(原拼写错误,改用 handleNaming())、Watcher 旧版配置回退机制,以及废弃的 RuleCollector、Tracer\Adapter\HttpClientFactory、Tracer\Aspect\JsonRpcAspect、ViewEngine\Contract\Enumerable 别名。

建议升级后用全局搜索(如 grep -r "getQueueName\|forceIndexes\|str_replace_once" app/)检查残留引用。

六、优化(Optimized)

基础设施与性能

  • 优化 Hyperf\Di\ReflectionManager::getAllClassesByFinder() 从文件读取内容的实现(PR #6804),减少反射扫描阶段的开销。
  • 事件监听器提供者为非匿名事件类增加缓存,避免重复的监听器解析(PR #7658)。
  • Arr::shuffle 增强为支持自定义随机引擎(PR #7142);toCssClasses / toCssStyles 直接使用输入数组简化逻辑(PR #7431)。
  • 使用 PHP 8.4+ 函数(带 polyfill)现代化 array 工具与 JSON 校验逻辑(PR #7523),意味着低版本 PHP 通过 polyfill 保持行为一致。
  • 新增 Symfony 7.4 兼容性,支持批量命令注册(PR #7620)。

协程与日志

  • Hyperf\Coordinator\Timer::tick() 的回调现在运行在 Hyperf\Coroutine\wait() 内部,确保定时任务在独立、受管理的协程上下文中执行;同时 wait() 方法会优先检查容器中是否存在 Hyperf\Coroutine\Waiter(PR #7761)。
  • 优化 StreamHandler 在协程并发场景下创建日志目录时的竞态问题(PR #7796,v3.2.4)。
  • StdoutLogger 输出格式新增时间戳前缀(PR #7621)。

gRPC 与 Nacos

  • Parser::parseResponse 返回值从 Grpc\StringifyAble 替换为 Google\Rpc\Status 对象,标准化错误信息的携带方式(PR #7653)。
  • 支持 Nacos v1、v2 及 v3 从实例列表中读取主机地址(PR #7790,v3.2.4)。

七、新增能力(Added)

1. 辅助函数:existent() 与 assert_instanceof()

v3.2.3 与 v3.2.4 分别新增两个 Hyperf\Support 命名空间下的全局函数,实现位于 src/support/src/Functions.php:

  • existent(mixed $value): mixed:确保值不为 null,遇 null 抛出 InvalidArgumentException,常用于收窄“可能为空”的类型推断,配合 PHPStan 的 @phpstan-assert !null 注解实现静态分析收窄。
  • assert_instanceof(mixed $value, string $interface): mixed:断言值实现指定接口/类,失败时抛出包含实际类型信息的 InvalidArgumentException,成功则原样返回,可用于依赖注入边界校验与测试断言。
<?php
use function Hyperf\Support\existent;
use function Hyperf\Support\assert_instanceof;

$config = existent($this->config->get('app.key')); // null 时抛异常

$listener = assert_instanceof($listener, ListenerInterface::class); // 类型不符时抛异常

2. 异步队列(async-queue)

// config/autoload/async_queue.php
return [
    'default' => [
        'enable' => true,          // 是否自动注册消费者进程(v3.2 新特性)
        'driver' => RedisDriver::class,
        'redis' => ['pool' => 'default'],
        'channel' => '{queue}',
        'timeout' => 2,
        'retry_seconds' => 5,
        'handle_timeout' => 10,
        'processes' => 1,          // 消费者进程数
        'concurrent' => ['limit' => 10],
        'max_messages' => 0,
    ],
];

3. 契约与集合

  • Hyperf\Contract\Jsonable 新增 toJson 方法(PR #6761)。
  • 为 HTTP 响应新增 Htmlable 契约接口(PR #6794),允许响应对象直接输出 HTML。
  • Hyperf\Pipeline\Pipeline::finally()(PR #7247):在管道末端追加最终回调,适合统一收尾逻辑。
  • Hyperf\Collection\Collection::shift() / pop() 支持一次取出多个元素(PR #7274)。
  • Hyperf\Collection\Arr 新增 partition() 与 reject()(PR #7302)。
  • Hyperf\Context\Context 支持 Macroable(PR #7312),可为其动态扩展方法。
  • Hyperf\Support\Fluent 得到改进(PR #7214)。

4. 数据库与测试

  • 新增 hyperf/database-sqlserver 包(PR #7717),SQL Server 支持独立成包,见仓库 src/database-sqlserver。
  • 新增 PHP 8.4 的 PDO 子类支持(PR #7019)。
  • QueryException 新增连接名(PR #7198),排查数据库异常时能直接定位到具体连接。
  • 新增 NonCoroutine 注解(PR #7605),用于灵活控制测试执行方式(标注的方法/类在测试中可脱离协程环境运行)。

5. 搜索引擎

  • 新增对 elasticsearch 8.x(PR #7202)与 9.x(PR #7629)的支持,配合依赖升级 ^8.0 || ^9.0,可在新版 ES 集群上直接使用。

八、行为变更(Changed)

  • hyperf/database 中 deleted_at 的默认类型变更为 datetime(PR #6760),软删除时间列的生成与迁移结果随之变化。
  • Hyperf\Database\Query\Builder::limit() 在传入值小于零时抛出异常(PR #7208),阻止非法 SQL 生成。
  • str_getcsv 使用空字符串作为 escape(PR #7372),与 PHP 8.4 的默认要求对齐。
  • influxdb/influxdb-php 替换为 influxdata/influxdb-client-php(PR #7462),使用 InfluxDB 的组件需调整客户端 API 调用方式。
  • 变更 logger 与 cache 的配置结构(见上文破坏性变更第 3、4 条)。
  • async-queue 术语统一:$queue → $pool、getQueueName() → getPoolName()。

九、修复(Fixed)

v3.2.0 修复

  • 修复 sortByMany() 与 sortBy() 返回结果不一致的 bug(PR #6934)。

v3.2.1 修复与优化

  • 修复 ModelRewriteInheritanceVisitor 无法在 gen:model 脚本中使用的问题(PR #7760)。
  • 新增 Hyperf\Logger\Handler\StreamHandler,该 handler 不含 set_error_handler 副作用(PR #7759),避免协程场景下错误处理器被意外覆盖。
  • Timer::tick() 与 wait() 的协程上下文优化(PR #7761)。

v3.2.2 修复

  • 修复 Hyperf\Validation\Concerns\ValidatesAttributes::validateMultipleOf 无法支持 float 类型校验的问题(PR #7768)。
  • 修复 gen:migration-from-database 命令无法使用的问题(PR #7771)。
  • 修复 Hyperf\Di\ScanHandler\ProcScanHandler 无法使用的问题(PR #7774)。
  • 修复 MorphTo 关联预加载指定字段时的 Bug(PR #7788)。

v3.2.3 修复

  • 修复模型生成时 @property 类型错误,例如将 @property int $id 修正为 @property ?int $id(PR #7782),使 IDE 与静态分析能正确识别可空主键。
  • 修复 Hyperf\ModelCache\Cacheable 的 PHP 注释(phpdoc)(PR #7784、#7785)。
  • 修复 Hyperf\Database\Model\Builder 的 PHP 注释(phpdoc)(PR #7786)。

十、升级检查清单

基于上述变更,将现有项目升级到 v3.2 时可按下述清单逐项核对:

  1. 环境与依赖:确认 PHP >=8.2;按“依赖升级清单”更新 composer 约束并重新 composer update;若使用 Monolog 请确认已是 3.x。
  2. 配置迁移:将 config/autoload/logger.php 迁移为 default + channels 结构;将 config/autoload/cache.php 迁移为 default + stores 结构;可用 src/logger/publish/logger.php 与 src/cache/publish/cache.php 作为迁移后的参考模板(也可用 php bin/hyperf.php vendor:publish 重新发布配置)。
  3. 代码重命名:全库替换 getQueueName() → getPoolName()、$queue → $pool(async-queue 相关);替换 forceIndexes() → forceIndex()、str_replace_once() → strReplaceOnce()。
  4. 移除项清理:删除对 v3.2 已移除符号(见“移除的废弃代码”一节)的所有引用。
  5. Carbon 语义核对:检查所有 diffInDays() 调用点,按需补充 $absolute;createFromTimestamp() 显式传时区。
  6. PHP 8.4 适配:为所有 fputcsv / fgetcsv 调用补上 escape: ''。
  7. Swow 场景:在 config/autoload/dependencies.php 中绑定 ResponseEmitterInterface => ResponseEmitter。
  8. 新特性尝鲜:按需启用 async-queue 配置自动注册(enable => true)、NonCoroutine 注解、Pipeline::finally()、existent() / assert_instanceof() 等新能力。

完成以上步骤后,即可平滑过渡到 v3.2,并享受 elasticsearch 8/9.x、PHP 8.4、Symfony 7.4 等上游生态带来的红利。

登录后查看全文
hyperf