Hyperf 3.1 全版本更新记录深度解析:从 v3.1.0 到 v3.1.71 的功能演进、修复清单与升级指南
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)验证行为是否符合预期。