Hyperf 3.1 全版本更新记录深度解析:从 v3.1.0 到 v3.1.71 的功能演进、修复清单与升级指南

原创2026-10-08 18:26:261,888 阅读
文章标签:后端微服务

Hyperf 3.1 全版本更新记录深度解析:从 v3.1.0 到 v3.1.71 的功能演进、修复清单与升级指南

Hyperf 3.1 系列自 2023 年 12 月发布 v3.1.0 起,历经 71 个补丁版本,持续为 PHP 协程框架用户带来数据库、协程、验证器、消息队列等核心组件的功能增强与稳定性修复。本文以官方 版本更新记录 为骨架,结合仓库源码逐条展开关键变更的底层实现,帮助你在升级或选型时准确判断每个版本带来的影响。

版本概况与发布节奏

Hyperf 3.1 从 2023-12-01 的 v3.1.0 起步,到 2026-08-07 的 v3.1.71 收尾,保持了约两周一次的补丁发布节奏。整体变更可分为四类:

  • 新增(Added):引入新组件、新注解、新配置项与新方法,是功能演进的动力;
  • 修复(Fixed):针对数据库、Redis、协程调度、验证器等高频场景的缺陷修补;
  • 优化(Optimized):性能、代码结构、类型注解与日志输出的改进;
  • 移除 / 变更 / 即将废弃(Removed / Changed / Deprecated):对旧接口的清理与行为调整,升级前需重点评估。

v3.1.0:大版本基线确立

v3.1.0 是 3.1 系列的奠基版本,其中包含大量结构性调整,升级前务必对照检查。

依赖库最低版本提升

v3.1.0 将核心依赖的最低版本整体抬高,与 composer.json 中当前 require 声明的 php >= 8.2、ext-swoole >= 5.0 保持一致:

依赖 最低版本
PHP 8.1(当前仓库要求 >= 8.2)
Swoole 5.0
hyperf/engine 2.0
PHPUnit 10.0

同时 v3.1.0 明确不再支持 Swoole 4.x(#5813),并移除了 setAccessible 调用——PHP 8.1 起反射方法默认可访问,无需再显式设置。若你的项目仍运行在 Swoole 4.x 或 PHP 8.0 环境,升级到 3.1 前必须先行升级运行环境。

Swow 运行引擎支持

v3.1.0 为 reactive-x 与 socketio-server 补齐了 Swow 引擎支持(#5843、#5844),让不依赖 Swoole 扩展的场景也能使用这两类组件。

新组件与关键能力

  • hyperf/helper 组件:提供全局助手函数,见 src/helper;
  • hyperf/polyfill-coroutine 组件:为未安装 Swoole 扩展的环境提供协程兜底能力,见 src/polyfill-coroutine;
  • hyperf/stdlib 组件:标准库能力补充(#6082;
  • Psr7Plus 与 Pest 支持:前者用于 HTTP 消息处理,后者为测试框架集成;
  • AsCommand 注解与 ClosureCommand(#5930、#5934):允许通过注解声明命令行任务,或以闭包方式直接注册命令,显著降低自定义命令的样板代码;
  • Crontab 语义化规则设置(#6039):定时任务调度表达式可读性更强。

数据库层增强

v3.1.0 对 ORM 与查询构造器做了大量扩充,是后续版本数据库功能演进的起点:

  • 支持使用枚举进行数据库更新与插入(#5849);
  • 模型支持自定义枚举转换(#5925、#5926);
  • 新增 toRawSql()(#5898)与 getRawQueryLog()(#5906),便于调试 SQL;
  • Query\Builder::addSelect 支持传入 QueryBuilder(#6259);
  • 新增助手函数 data_forget(#5915)。

组件行为变更

v3.1.0 还包含若干需要注意的行为调整:

  • AMQP:Hyperf\Amqp\Result 与 Hyperf\Amqp\Message\Type 改用枚举替代常量(#5961);
  • JSON RPC:HTTP 协议下不再因非 200 状态码移除节点(#5943);
  • Base62:Base62::decode 遇到不正确数据时抛出 InvalidArgumentException 而非 TypeError(#6022);
  • metric 组件:默认 Redis key 变更(#5847),Prometheus 组件库从默认依赖改为建议依赖。

新增能力的版本时间线

协程与并发原语

协程工具类是 3.1 系列的高频新增区域:

  • v3.1.66:新增 Pool::flushAll() 与 PoolFactory::flushAll()(#7698 可以看到其实现:循环调用 flushOne(true) 直到通道内连接耗尽,用于一次性回收当前连接池的全部连接;
  • v3.1.63:Hyperf\Coroutine\Barrier(#7343),用于协程间的同步屏障;
  • v3.1.51:新增 Hyperf\Coroutine\WaitConcurrent(#7263,它继承 Concurrent 并组合 WaitGroup,create() 时 add() 计数,任务执行完毕在 finally 中 done(),最后通过 wait(timeout) 统一等待,适合限流并发 + 批量等待的场景;
  • v3.1.50:新增 Hyperf\Coroutine\Mutex(#7224;
  • v3.1.54:新增 Hyperf\Coroutine\Coroutine::list()(#7286),可枚举当前协程;
  • v3.1.1:新增 Coroutine::fork() 与 Coroutine::pid()(#6342)。

其中 v3.1.70/v3.1.71 对 Hyperf\Coordinator\Timer::tick() 的两次修复值得关注:v3.1.70 将 tick() 的执行逻辑放入 Hyperf\Coroutine\wait() 中,确保运行在独立协程环境;v3.1.71 修复其因 wait() 导致 10 秒超时的问题。wait() 的容器感知逻辑见 Functions.php:优先从容器取出 Waiter 实例,否则临时创建——这正是 v3.1.70 中"优先检查 Waiter 是否存在于容器中"优化的落地位置。

数据库与查询构造器

3.1 系列在数据库层新增的方法密度最高,按版本归纳:

  • v3.1.66:Builder::withoutForeignKeyConstraints()、ForeignKeyDefinition 新增 cascadeOnDelete()、restrictOnDelete()、noActionOnDelete()、restrictOnUpdate()、nullOnUpdate()、noActionOnUpdate();QueryBuilder 新增 whereJsonContainsKey()、orWhereJsonContainsKey()、whereJsonDoesntContainKey()、orWhereJsonDoesntContainKey();
  • v3.1.61:Model\Builder::incrementOrCreate()、Model::isSoftDeletable()、Model\Builder::except()、BelongsTo::disassociate()(dissociate() 的别名)、Arr::push()/Arr::array()/Arr::hasAll()、Grammar::whereValueBetween();
  • v3.1.52:Connection::scalar() 读取首行首字段;
  • v3.1.51:Model\Builder::createOrFirst()/createOrRestore()、Query\Builder::existsOr()/doesntExistOr()/sole()、Model::discardChanges()/hasAppended();
  • v3.1.45:Model\Builder::findOr()、Arr::shuffleAssoc()、Model\Collection::setVisible()/setHidden();
  • v3.1.44:Blueprint 新增 nullableUuidMorphs/uuidMorphs/nullableNumericMorphs/charset()/collation()/tinyText();
  • v3.1.37:Query\Builder::whereNone()/orWhereNone();
  • v3.1.27:Schema::getViews()/hasView()、Schema\Builder::getIndexes()/hasIndex()/getIndexListing()、BuildsQueries::lazy()/eachById()、Model::updateOrFail()、QueriesRelationships::whereMorphRelation()/orWhereMorphRelation();
  • v3.1.26:Schema::getTables()、BuildsQueries::chunkById()/chunkByIdDesc()、HidesAttributes::makeHiddenIf()/makeVisibleIf();
  • v3.1.25:基于 cursor 的分页机制(#6809)、Model::query()->touch()、Builder::qualifyColumns()/valueOrFail()/load*、BuildsQueries::chunkMap()、lazyById()/lazyByIdDesc()、Schema::createDatabase()/dropDatabaseIfExists();
  • v3.1.23:LazyCollection、Query\Builder 的 whereAll/orWhereAll/whereAny/orWhereAny、Lateral Join、whereJsonOverlaps/orWhereJsonOverlaps/whereJsonDoesntOverlap、insertOrIgnoreUsing;
  • v3.1.21:Query\Builder::useIndex()/forceIndex()/ignoreIndex();
  • v3.1.22:Query\Builder::explain();
  • v3.1.24:Query\Builder 的 IncrementEach/DecrementEach。

v3.1.67 还为验证器规则 exists 和 unique 增加了模型类名写法支持,例如 exists:App\Model\User,id(#7459)。

验证器规则扩充

验证器规则在多个版本持续扩充:

  • v3.1.53:新增 contains、extensions、hex_color(#7313);
  • v3.1.46:新增 exclude(#7148)以及 accepted_if、ascii、date_equals 等(#7150);
  • v3.1.28:新增 prohibiti(#6885);
  • v3.1.25:新增 list(#6811)。

同时修复了多项验证器问题:v3.1.62 支持通过场景值覆写参数验证规则(#7469);v3.1.63 修复 ValidationRuleParser::parseParameters() 不支持 PHP 8.4 的问题(#7536);v3.1.9 修复 decimal 规则无法与 size 配合的问题(#6482);v3.1.59 修复 exclude 规则不可用的问题(#7427);v3.1.64 修复使用不存在的场景值导致报错(#7596)。

消息队列与 RPC

  • v3.1.64:异步队列新增执行结果枚举 Hyperf\AsyncQueue\Result(#7601),且 AsyncQueueMessage 注解支持定义在 protected/private 方法上(#7604),消费者进程参数 $queue 重命名为 $pool(#7615);
  • v3.1.65:Kafka 新增事件 FailToAck 与 FailToRequeue(#7585);
  • v3.1.61:Kafka 新增常量 KafkaStrategy::STICKY_ASSIGNOR(#7499);
  • v3.1.60:Kafka 新增配置项 produce_retry 与 producer_retry_sleep(#7473);
  • v3.1.62:修复 Kafka 消费者配置成员变量 $pool 无法正常使用的问题(#7547);
  • v3.1.54:修复 Kafka 消息生产者连接断开后无法重连的问题(#7334);
  • v3.1.34:新增命令 queue:dynamic-reload(#6979);
  • v3.1.27:Kafka ConsumerManager 新增事件 BeforeLongLangConsumerCreated 与 AfterConsumerConfigCreated(#6897、#6899)。

缓存与 Redis

  • v3.1.67:修复 hyperf/cache 内存适配器不支持默认 ttl 的问题(#7703);
  • v3.1.56:CacheAHead 注解新增 runAsync 参数,可异步初始化缓存(但返回值会为 Null)(#7404);修复内存适配器不支持 setMultiple 的问题(#7410);
  • v3.1.43:修复 CacheAHead 不能使用默认 ttl 的问题(#7109);
  • v3.1.28:hyperf/cache 新增配置项 cache.*.options.pool,用于主动选择 Redis 实例(#6891);
  • v3.1.11:hyperf/cache 新增 SqliteDriver 适配器(#6562);
  • v3.1.10:hyperf/cache 新增内存缓存驱动 MemoryDriver(#6542),并新增 database-sqlite 组件(#6533);
  • v3.1.63:修复 Redis 集群 context 参数在未设置密码时不生效的问题(#7554);
  • v3.1.53:新增 Hyperf\Redis\Event\CommandExecuted::getFormatCommand()(#7311);
  • v3.1.51:新增 Hyperf\Redis\Event\CommandExecuted(#7269);
  • v3.1.18:Redis 连接池新增 getConfig() 方法(#6674);
  • v3.1.69:修复长生命周期环境下 Redis::pipeline() 内存泄漏(#7734),并修复 RedisDriver::keys 在 sMembers 返回非数组时无法返回数组的问题(#7736)。

消息与字符串工具

  • v3.1.65:新增 Str::uuidv7()(#7644,依赖 ramsey/uuid 包,未安装时会抛出提示异常;
  • v3.1.29:新增 Str::chopStart() 与 Str::chopEnd()(#6917,分别去除字符串头部/尾部的指定子串;
  • v3.1.17:新增 Str::trim()(#6652);
  • v3.1.13:新增 Str::apa()(#6576,内置了 and、the 等小写词表与连字符处理逻辑;
  • v3.1.3:twig 模板引擎新增 template_suffix 配置(#6402);
  • v3.1.36:Cookie 增加 partitioned 支持(#6971)。

命令与开发工具

  • v3.1.66:文件生成命令新增 --path 选项指定生成位置(#7670);
  • v3.1.62:migrate:rollback 新增 batch 参数(#7531);
  • v3.1.56:AsCommand 与 ClosureCommand 增加 coroutine 选项(#7392);
  • v3.1.51:新增 Hyperf\Command\Concerns\Prohibitable(#7265);使用命令创建文件后支持用 cursor 编辑器自动打开对应文件(#7273);
  • v3.1.34:#[AsCommand] 注解支持 static 方法调用(#6978);
  • v3.1.19:gen:constant 脚本增加 type 选项,可生成 const 或 enum 两种写法的常量/枚举类(#6681);
  • v3.1.13:MigrateCommand 增加 --graceful 选项(#6590);
  • v3.1.55:logger 配置文件支持 callable 方式(#7365)。

值得重点关注的修复清单

数据库与迁移

  • v3.1.60 修复 migrate:fresh 无法删除默认表(#7447)以及 Migrator::reset() 不支持 string 参数(#7449);
  • v3.1.40 修复 migrate 的 --database 选项不生效(#7051);
  • v3.1.45 修复 migration 主动配置 connection 不生效(#7133);
  • v3.1.54 修复使用 Blueprint 建表时主动配置主键导致报错(#7328);
  • v3.1.57 修复 sqlite 数据库迁移无法正常使用(#7414);
  • v3.1.69 修复 PostgresProcessor 在 columns 为 null 时无法处理索引和外键(#7737);
  • v3.1.67 修复 Query\Builder::eachById 无法使用(#7705);
  • v3.1.68 修复 BuildsQueries::getOriginalColumnNameForCursorPagination 无法使用(#7738)。

协程与运行时

  • v3.1.71 修复 Coordinator\Timer::tick() 因 Coroutine\wait() 导致 10s 超时;
  • v3.1.69 修复 Swoole 6.2.0 下 getUri()->getHost() 返回服务器 IP 而非域名(#7745),原因是 getUriFromGlobals() 中 server_addr 优先级高于 header 中的 host;
  • v3.1.16 修复定时任务偶发跳过任务不执行(#6633);
  • v3.1.11 修复定时任务睡眠间隔偶发跳秒(#6563);
  • v3.1.10 为 retry 增加每次重试可手动设置延时时长的能力(#6539)。

网络与协议

  • v3.1.69 修复 Hyperf\HttpServer\Response 的 Macroable 无法工作(#7731);
  • v3.1.68 修复使用 nacos 时因服务不存在导致无法启动(#7739)以及 Aws\Handler\GuzzleV6\GuzzleHandler 找不到(#7740);
  • v3.1.53 修复 Hyperf\Testing\Client 非 POST 请求不支持 Json 结构(#7309)、WebSocket 客户端不支持接收 CloseFrame(#7318);
  • v3.1.32 修复 socketio-server 在 Swow 引擎下无法使用(#6953);
  • v3.1.31 支持 watcher 组件自动重载 .env(#6936);
  • v3.1.12 修复 $request->all() 读取入参时数字 key 被重置(#6566);
  • v3.1.6 优化 DispatcherFactory 使用 require 代替 require_once(#6472)。

升级迁移指南

接口变更与重命名

  • AMQP 枚举化:v3.1.0 起 Result 与 Message\Type 为枚举,涉及 AMQP 消费者/生产者的常量判断需同步调整;
  • 队列参数重命名:v3.1.64 将异步队列消费者进程参数 $queue 重命名为 $pool;
  • 废弃方法:v3.1.15 标记 WebSocketHandeShakeException 即将废弃,改用 WebSocketHandShakeException(#6621);v3.1.0 将 Hyperf\DB\PgSQL\PgSQLConnection::str_replace_once 与 PostgreSqlSwooleExtConnection::str_replace_once 标记为即将废弃,分别改用 strReplaceOnce;
  • sortByMany() 行为调整:v3.1.30 修复其在新版本重置索引导致 BC 的问题,v3.2 起返回值与 sortBy() 一致,不再重置索引。

组件移除

  • v3.1.0 移出废弃组件 swoole-tracker(#6244)与废弃的 Hyperf\Coroutine\Traits\Container(#6043);
  • v3.1.57 移除 Hyperf\Utils 组件(#7411),相关工具方法已迁移至 hyperf/support、hyperf/stringable、hyperf/collection 等组件;
  • v3.1.0 起 Str 默认移除缓存逻辑(#5859),v3.1.62 优化读取 composer.lock 的代码实现(#7258)。

配置项新增

  • Kafka:produce_retry、producer_retry_sleep(v3.1.60);
  • AMQP:connection_name 用于自定义连接名称(v3.1.50,#7233)、注解新增 poolName 参数(v3.1.0,#5960);
  • rate-limit:rate_limit.storage.options.expired_time(v3.1.24,#6795);
  • cache:cache.*.options.pool(v3.1.28);
  • swagger:配置中可设置 servers 与 info(v3.1.45,#7149),新增 processors 配置追加自定义处理器(v3.1.0,#6338)。

结语

Hyperf 3.1 系列以"数据库能力补全 + 协程原语丰富 + 生态组件对齐"为主线,71 个版本累计带来上百项新增与修复。对开发者而言,数据库与验证器是升级收益最大的模块,AMQP 枚举化、队列参数重命名、Utils 组件移除则是迁移成本最高的三点。建议升级时以本记录为对照清单,逐版本核对涉及的配置项与接口,并通过仓库内的组件测试(如 src/coroutine/tests、src/database/tests)验证行为是否符合预期。

登录后查看全文
hyperf