Hyperf 3.1 版本演进全解析:从 v3.1.0 到 v3.1.71 的关键变更、新能力与升级指南

原创2026-10-06 20:07:251,956 阅读
文章标签:后端微服务

Hyperf 3.1 版本演进全解析:从 v3.1.0 到 v3.1.71 的关键变更、新能力与升级指南

本文以官方 docs/en/changelog/3.1.md 为主线,系统梳理 Hyperf 3.1 系列从 2023 年 12 月 v3.1.0 发布到 2026 年 8 月 v3.1.71 的全部版本变更,涵盖依赖基线升级、协程调度、数据库、Redis、验证、Kafka、gRPC 等核心组件的新增能力与重要修复,并结合仓库源码说明底层实现,帮助你评估升级影响、快速定位可用新特性。读完本文,你将能对照版本号逐项核对升级要点,并把关键新 API 直接运用到自己的业务代码中。

阅读提示:本文涉及的所有源码路径均相对于仓库根目录;官方发布历史以仓库中的 CHANGELOG-3.1.md 及 CHANGELOG.md 为准,本文只覆盖 3.1 分支的变更记录。

1. v3.1.0:3.1 分支的基线版本

v3.1.0(2023-12-01)是 3.1 系列的第一个正式版本,本节的变更决定了整个 3.1 分支的运行时基线,升级到 3.1.x 的开发者应首先核对这里的依赖与环境要求。

1.1 依赖基线升级

v3.1.0 对运行环境提出了更高的要求:

依赖项 3.1.0 要求 说明
PHP >=8.1 低于 8.1 的 PHP 版本不再受支持
Swoole >=5.0 不再支持 Swoole 4.x(见 3.1.0 Removed 条目)
hyperf/engine ^2.0 底层协程引擎随之升级
phpunit/phpunit ^10.0 测试框架基线同步升级

同时,3.1.0 增加了对 Swow 协程引擎的适配,reactive-x 与 socketio-server 两个组件开始支持 Swow(PR #5843、#5844),这使得使用 Swow 作为协程运行时的项目可以覆盖更多组件。

1.2 新组件与 PSR-7 Plus 支持

  • 新增 hyperf/helper 与 hyperf/polyfill-coroutine 两个组件。
  • 全面支持 Psr7Plus 接口:http-message 组件在 PR #5828 中先行接入,随后 PR #5839 让所有组件统一支持 Swow 的 psr7-plus 接口,为 Swow 引擎下的 HTTP 消息处理提供了统一的抽象。
  • 新增 hyperf/stdlib 组件(PR #6082),并把字符串相关的 Str 操作迁移至 hyperf/stringable。
  • 新增 hyperf/carbon(v3.1.14 加入)与 hyperf/migration-generator(用于从数据库反向生成迁移文件,PR #5967)。

1.3 命令系统:AsCommand 注解与 ClosureCommand

PR #5930、#5934 引入了 AsCommand 注解与 ClosureCommand,让定义命令不再必须继承 Hyperf\Command\Command:

use Hyperf\Command\Annotation\AsCommand;

#[AsCommand(name: 'demo:hello', description: 'Say hello')]
class HelloCommand
{
    public function handle(): void
    {
        // 命令逻辑
    }
}

ClosureCommand 则允许直接以闭包方式注册命令。在 v3.1.56 中又为 AsCommand 与 ClosureCommand 增加了 coroutine 选项(PR #7392),可以指定命令是否在协程中执行。

1.4 协程、数据库与查询构建器的新能力

  • 协程调度:Hyperf\Coroutine\Coroutine 新增 fork() 与 pid() 方法(PR #6342)。
  • 数据库:模型属性支持与 Enum 互转(PR #5925、#5926);Query\Builder 新增 toRawSql()(PR #5898);Database\Connection 新增 getRawQueryLog()(PR #5906)。
  • 辅助函数:新增 data_forget()(PR #5915)、Str::isUrl()(PR #5914)、Arr::isList()(PR #5918)。
  • 缓存:hyperf/cache 注解新增 skipCacheResults(PR #5983、#5985)。
  • 异步队列:新增 Job::setMaxAttempts() 与 dispatch() 辅助函数(PR #5950)、Job::fail()(PR #6124)。
  • 定时任务:支持语义化 crontab 规则(PR #6039),并新增生命周期事件(PR #5994)。

1.5 行为变更与废弃项

v3.1.0 同时清理了大量历史包袱,升级时需特别注意以下行为变化:

  • Redis:当配置了非法的 redis option key 时改为直接抛出异常(不再静默忽略)。
  • Load Balancer:json-rpc http transporter 在状态码不是 200 时不再从负载均衡节点列表移除该节点(PR #5943)。
  • AMQP:Hyperf\Amqp\Result 与 Hyperf\Amqp\Message\Type 由 class 改为 enum(PR #5961),如果你的业务代码用字符串常量与之比较,需要迁移为枚举比较。
  • config 组件:多级目录配置可通过 config('a.c') 读取 autoload/a/c.php 中的内容(PR #6128)。
  • 废弃清理:移除了 Hyperf\Utils 中未使用的代码与过期方法、swoole-tracker 组件(PR #6244)、Hyperf\Coroutine\Traits\Container(PR #6043)等。
  • Base62 解码:Base62::decode() 解码非法数据时抛出 InvalidArgumentException 而非 TypeError(PR #6022)。

2. 数据库层演进:从查询构建器到 Schema 蓝图

3.1 系列在 hyperf/database 上持续投入,绝大多数新增方法都能在 src/database/src 中找到对应实现。

2.1 Query\Builder 的查询能力扩展

按时间顺序,Query Builder 新增了大量方法:

  • 条件查询:whereAll/orWhereAll、whereAny/orWhereAny(PR #6767,v3.1.23);whereNone/orWhereNone(PR #7015,v3.1.37);whereJsonContainsKey 等 4 个 JSON 键判断方法(PR #7699,v3.1.66)。
  • JSON 查询:whereJsonOverlaps、orWhereJsonOverlaps、whereJsonDoesntOverlap(PR #6782,v3.1.23)。
  • Lateral Join:支持 SQL 的 Lateral Join 写法(PR #6774,v3.1.23)。
  • 索引提示:useIndex、forceIndex、ignoreIndex(PR #6740,v3.1.21)。
  • 批量更新:incrementEach/decrementEach(PR #6792,v3.1.24)。
  • 排序重设:reorder() 清除并重设排序(PR #7016,v3.1.38)。
  • 位运算支持:where bit functions and operators(PR #6950,v3.1.32)。
  • 存在性判断:existsOr/doesntExistOr(PR #7259,v3.1.51)、sole()(PR #7260,v3.1.51,查询必须恰好返回一条记录)。
  • 值区间:Grammar 层新增 whereValueBetween()(PR #7518,v3.1.61)。
  • 插入忽略:insertOrIgnoreUsing(PR #6783,v3.1.23);updateOrInsert 空输入问题修复(PR #6818)。
  • SQL 解释:explain()(PR #6746,v3.1.22)。

2.2 模型与 Eloquent 风格方法

  • 创建/更新:incrementOrCreate()(PR #7480,v3.1.61)、updateOrFail()(PR #6884,v3.1.27)、createOrFirst() 与 createOrRestore()(PR #7255,v3.1.51,读取 null 时抛出异常的行为变化见 PR #7291)、discardChanges()(PR #7261)。
  • 查询辅助:findOr()(PR #7143,v3.1.45)、findOrFail() 加入 Model\Collection(PR #7192,v3.1.48)、valueOrFail()(PR #6820)、touch() 更新时间戳(PR #6814)、except()(PR #7486)、qualifyColumns()(PR #6815)。
  • 软删除:isSoftDeletable()(PR #7484,v3.1.61)。
  • 关系查询:whereRelation/orWhereRelation(PR #6844)、withWhereHas()(PR #6837)、whereMorphRelation/orWhereMorphRelation(PR #6878)、orHasMorph/orDoesntHaveMorph(PR #6851)。
  • 属性隐藏/显示:makeHiddenIf/makeVisibleIf(PR #6858)。
  • 分块与懒加载:chunkById/chunkByIdDesc(PR #6846)、eachById(PR #6876,其 bug 修复见 PR #7705)、lazy(PR #6866)、lazyById/lazyByIdDesc(PR #6822)、chunkMap()(PR #6821)。
  • 游标分页:cursor paginator 于 v3.1.25 引入(PR #6809),getOriginalColumnNameForCursorPagination 的修复见 PR #7738。
  • Cast 扩展:AsArrayObject(PR #7487)、AsCollection(PR #7607)、枚举互转(v3.1.0)。
  • 连接层:Connection::scalar() 取首行首列(PR #7200,v3.1.52);连接内置错误计数,异常过多时自动重置连接(PR #6085)。

2.3 Schema 构建器的演进

Schema 相关能力在 3.1 中大幅增强,集中在 src/database/src/Schema 目录:

  • 元数据查询:Schema::getTables()(PR #6845)、Schema::getForeignKeys()(PR #7059)、Schema::whenTableHasColumn/whenTableDoesntHaveColumn(PR #7024)、Builder::getIndexes()/hasIndex()/getIndexListing()(PR #6883)、Builder::getViews()/hasView()(PR #6864)。
  • Blueprint 方法:engine()(PR #7156)、charset()/collation()(PR #7070)、tinyText()(PR #7071)、nullableUuidMorphs/uuidMorphs/nullableNumericMorphs(PR #7063)。
  • 外键定义:ForeignKeyDefinition 新增 cascadeOnDelete()、restrictOnDelete()、noActionOnDelete()、restrictOnUpdate()、nullOnUpdate()、noActionOnUpdate()(PR #7693);Blueprint::foreign() 的返回类型修复解决了链式调用 references()、on() 时的静态分析报错(PR #7682)。
  • 数据库级操作:createDatabase/dropDatabaseIfExists(PR #6825);Builder::withoutForeignKeyConstraints()(PR #7684)。

2.4 数据库相关修复盘点

  • PostgreSQL:migrate:fresh 默认无法 drop 表的问题(PR #7447)、布尔值在模拟预处理与原生 SQL 下的处理(PR #7669)、PostgresProcessor 处理 columns 为 null 时的索引与外键(PR #7737)、gen:model 在 pgsql 下失效(PR #7400)、pdo connector 迁移问题(PR #7379)、connect_timeout 不生效(PR #7402)。
  • MySQL:启用 sql_require_primary_key 时主键创建失败(PR #7328)。
  • SQLite:database-sqlite 组件于 v3.1.10 加入(PR #6533),sqlite 迁移失效修复见 PR #7414。
  • 迁移命令:--database 选项不生效(PR #7051)、Migrator::reset() 不支持字符串路径(PR #7449)、迁移连接异常(PR #7133)、v3.1.62 为 migrate:rollback 增加 batch 选项(PR #7531)。

3. 协程与并发原语:3.1 的调度能力升级

3.1 Timer 协程上下文修复与等待机制

v3.1.70 与 v3.1.71 连续修复了 Hyperf\Coordinator\Timer 的协程调度问题(PR #7761、#7764):

  • v3.1.70:Timer::tick() 改为在 Hyperf\Coroutine\wait() 内部执行回调,确保回调运行在受管理的协程上下文中。
  • v3.1.71:修复 tick() 回调被 wait() 默认 10 秒超时截断的问题——Timer 在构造时使用 new Waiter(-1)(见 src/coordinator/src/Timer.php),将超时设为 -1(无限等待),避免长任务回调被误杀;wait() 方法也会先检查容器中是否存在 Hyperf\Coroutine\Waiter(见 src/coroutine/src/Waiter.php,Waiter::wait() 内部通过 Channel(1) + Coroutine::create 把闭包投递到子协程执行)。

因此在使用 v3.1.70 及更早版本的 tick() 执行耗时回调时,如果回调超过 10 秒会被超时中断;升级到 v3.1.71 后不再受该默认超时影响。

3.2 新增并发原语

  • Hyperf\Coroutine\Barrier(PR #7343,v3.1.54):继承自 Hyperf\Engine\Barrier(见 src/coroutine/src/Barrier.php),用于等待一组协程全部完成。
  • Hyperf\Coroutine\Mutex(PR #7224,v3.1.50):基于 Channel(1) 实现的可重入互斥锁,提供静态方法 lock(string $key, float $timeout = -1)、unlock(string $key, float $timeout = 5)、clear(string $key)(见 src/coroutine/src/Mutex.php)。lock 在超时或通道关闭时返回 false;unlock 超过 popTimeout 说明重复解锁,返回 false。
  • Hyperf\Coroutine\WaitConcurrent(PR #7263,v3.1.51):在 Concurrent 并发限制的基础上叠加 WaitGroup,create() 时 wg->add(),回调结束后 wg->done(),最后通过 wait() 阻塞等待全部完成(见 src/coroutine/src/WaitConcurrent.php)。典型用法:
use Hyperf\Coroutine\WaitConcurrent;

$concurrent = new WaitConcurrent(10); // 最多 10 个并发
foreach ($tasks as $task) {
    $concurrent->create(fn () => doSomething($task));
}
$concurrent->wait(); // 等待全部完成
  • Coroutine::list()(PR #7286,v3.1.52):列出当前进程内所有协程。

3.3 Redis 连接与协程锁修复

  • v3.1.59(PR #7394):使用带回调的 transaction 或 pipeline 时,连接立即释放回连接池。
  • v3.1.69(PR #7734):修复长时间运行环境下 Redis::pipeline() 的内存泄漏。
  • v3.1.69(PR #7736):RedisDriver::keys() 在 sMembers 返回非数组时仍返回数组的修复。
  • v3.1.63(PR #7554):Redis 集群在未配置 auth 或 auth 为 null 时参数上下文失效的修复。
  • v3.1.57(PR #7420):Redis 服务重启后 luasha 失效的修复。

Redis 相关代码可参考 src/redis/src 下的 Redis.php、RedisProxy.php 与 RedisFactory.php。

4. 验证、集合与字符串工具链

4.1 验证规则(hyperf/validation)

3.1 系列为验证组件新增了大量规则与方法:

  • 新规则:contains、extensions、hex_color(PR #7313,v3.1.53)、list(PR #6811,v3.1.25)、prohibiti(PR #6885,v3.1.28);decimal 与 size 组合修复(PR #6482)。
  • exists/unique 支持模型名:验证规则 exists 与 unique 支持直接使用 App\\Model\\User 这类模型类名(PR #7459,v3.1.67)。
  • 场景规则重写:支持按场景重写验证规则(PR #7469,v3.1.62)。
  • 排除规则:新增 exclude 规则(PR #7148,v3.1.46);exclude 不生效的修复见 PR #7427(v3.1.59)。
  • 缺失规则回退:v3.1.64 修复了验证规则未定义时的 BC 问题(PR #7596)。
  • 兼容性:ValidationRuleParser::parseParameters() 支持 PHP 8.4(PR #7536);validateMultipleOf() 兼容最新版 brick/math(PR #7791)。
  • 其余方法补充:accepted_if、ascii、date_equals 等缺失规则消息(PR #7150)。

4.2 集合与数组工具

hyperf/collection 组件新增的方法覆盖 src/collection/src:

  • Arr:shuffleAssoc(PR #7141)、sole()(PR #7600)、push()/array()(PR #7500)、hasAll()(PR #7502)、remove(PR #6471,v3.1.6)。
  • Collection:replace()/replaceRecursive()(PR #6501)、unshift(PR #6738)、getOrPut/getOrSet(PR #6784)、doesntContainStrict()(PR #7481)、before()/after()(PR #6869)、sortByMany 相关修复(PR #6925、#7124)。
  • LazyCollection:v3.1.23 引入(PR #6757),splitIn() 类型提示修复(PR #6848)。

4.3 字符串与 Fluent

  • Str:chopStart()/chopEnd()(PR #6917)、apa()(PR #6576)、trim 系列方法(PR #6652)、numbers() 与 fromBase64()(PR #6799)、Str::trim 默认规则修复(PR #7068)。
  • Fluent:InteractsWithData trait(PR #7476)、isEmpty/isNotEmpty/getIterator(PR #7466)。

5. 消息队列与 RPC:AMQP、Kafka、JSON-RPC 与 gRPC

5.1 AMQP(hyperf/amqp)

  • 连接名参数:新增 connection_name 参数用于指定 AMQP 连接名(PR #7233,v3.1.50)。
  • 路由键数组:Consumer 注解的 routingKey 支持数组(PR #6778)。
  • 交换器自动声明:生产消息时自动声明交换器(PR #6696);消费者消息的交换器声明优化(PR #6716、#6717)。
  • 消息类型:Message::getTypeString() 避免属性与 getter 方法冲突(PR #7741);ConsumerMessage::getQueue 返回类型修复(PR #6635)。

5.2 Kafka(hyperf/kafka)

  • 生产者重试配置:新增 produce_retry 与 producer_retry_sleep 配置项(PR #7473,v3.1.60),默认值见 src/kafka/publish/kafka.php:
return [
    // ...
    'produce_retry' => 3,       // 生产失败重试次数
    'produce_retry_sleep' => 0.1, // 每次重试间隔(秒)
];
  • 事件:新增 Hyperf\Kafka\Event\FailToAck 与 FailToRequeue(PR #7585,v3.1.65);ConsumerManager 新增 BeforeLongLangConsumerCreated 与 AfterConsumerConfigCreated 事件(PR #6897、#6899)。
  • 消费策略:新增 KafkaStrategy::STICKY_ASSIGNOR 常量(PR #7499,v3.1.61)。
  • 修复:消费者 $pool 属性不生效(PR #7547)、断网后生产者无法重连(PR #7334)。

5.3 JSON-RPC 与 RPC

  • 错误响应:v3.1.66 优化 JSON-RPC 核心中间件对 ValidationException 的处理,正确返回 INVALID_PARAMS 错误(PR #7687)。
  • 负载均衡:v3.1.0 起 http transporter 在非 200 状态码下不移除节点(PR #5943)。
  • rpc-multiplex:客户端响应解析不一致修复(PR #6500)、HostReaderInterface(PR #6504)、回调错误处理(PR #6668)。

5.4 gRPC 客户端

  • 多客户端负载均衡:新增 client_count 选项,可创建多个 gRPC 客户端以配合负载均衡(PR #7667、#7672,v3.1.66),相关实现见 src/grpc-client/src/BaseClient.php。
  • ping 方法:gRPC 客户端支持 ping()(PR #6373)。

6. 命令、进程与开发工具链

6.1 命令组件(hyperf/command)

  • AsCommand 支持静态方法(PR #6978,v3.1.34);新增命令 queue:dynamic-reload(PR #6979,v3.1.34)。
  • 命令选项自动补全:为 AsCommand 与 ClosureCommand 提供选项补全(PR #6734)。
  • 新增 Hyperf\Command\Concerns\Prohibitable trait(PR #7265,v3.1.51),用于标记禁止运行的命令。
  • 命令异常错误信息优化(PR #6962);命令在 finally 块中恢复 coordinator(PR #7545,v3.1.62)。
  • Console::command() 增加 @param-closure-this 注解提升 IDE 支持(PR #7611,v3.1.64)。

6.2 代码生成与 watcher

  • 生成器 --path 选项:v3.1.66 起生成命令支持 --path 指定自定义输出位置(PR #7670)。
  • gen:model:支持从 trait 生成注释(PR #7279);自动生成属性注释中的 use(PR #6435、#6437);RewriteReturnType 注解用于重写返回类型(PR #6426);支持在编辑器 cursor 处自动打开新文件(PR #7273)。
  • gen:constant:新增 type 选项,可选 const 或 enum(PR #6681)。
  • watcher:支持在监听时重载 .env(PR #6936);使用 PHP_BINARY 作为默认 PHP 二进制路径(PR #6661);修复 php 路径含空格的问题(PR #7424);phar:build 打包速度优化与 declare 主文件破坏修复(PR #7040、#7034);FswatchDriver 空读取不再触发重启(PR #6686)。

6.3 进程与池

  • 连接池:新增 Pool::flushAll() 与 PoolFactory::flushAll() 一次性关闭所有连接(PR #7698,v3.1.66);连接释放事件(PR #6613,v3.1.15)。
  • 进程:ProcessManager 的 running 状态更清晰(PR #6172)。
  • 非协程 task worker:新增 UnsetContextInTaskWorkerListener,用于清理连接上下文(PR #6431,v3.1.5)。

7. 缓存、限流、日志与可观测性

7.1 缓存(hyperf/cache)

  • 新驱动:MemoryDriver(PR #6542,v3.1.10)、SqliteDriver(PR #6562,v3.1.11)。
  • Redis 实例选择:支持 cache.*.options.pool 选择 redis 连接池实例(PR #6891)。
  • 修复:内存驱动默认 ttl 不生效(PR #7703);CacheAHead 默认 ttl 问题(PR #7109);setMultiple 内存驱动失效(PR #7410)。
  • 缓存预取优化:CacheAheadAspect 在另一个协程中写缓存,不再阻塞当前协程(PR #6608);CacheAHead 新增 runAsync 参数(PR #7404)。

7.2 限流(hyperf/rate-limit)

  • 新增配置 rate_limit.storage.options.expired_time(PR #6795,v3.1.24)。
  • 存储切换器改进(PR #6301);RateLimitAnnotationAspect::getWeightingAnnotation() 在配置 rate_limit.storage 时失效的修复(PR #6374)。

7.3 日志与追踪

  • logger:支持 callable 类型的日志配置(PR #7365,v3.1.55);handler 定义简化(PR #5973);新增 Hyperf\Framework\Logger\ConsoleLogger(PR #7028,v3.1.38),并支持在 watcher 中运行(PR #7033)。
  • tracer:将请求体与响应体加入追踪(PR #6793,v3.1.24);客户端标签优化(PR #7676);HttpClientFactory 的 Content-Type 类型由 int 修正为 string(PR #7791)。

8. WebSocket、Web 与 Swagger

8.1 WebSocket

  • websocket-client:支持设置请求头(PR #6632);push/disconnect 返回结果(PR #6648);关闭帧丢失修复(PR #7318)。
  • websocket-server:新增日志记录器(PR #6665);WebSocketHandeShakeException 废弃,改用 WebSocketHandShakeException(PR #6621);websocket sender 支持 Swow(PR #6961);无效消息处理器导致 fatal exception 修复(PR #7231)。
  • socketio-server:Swow 引擎支持修复(PR #6953);带 ? 无 query 的数据解析修复(PR #6689)。

8.2 Web 与 HTTP

  • #[AutoController] 提供默认方法,可新增 options 方法配合 CORS 中间件(PR #6998,v3.1.36)。
  • Cookie:分区支持(PR #6971);SetCookie::fromString 类型校验修复(PR #6836);cookie 值为 "" 时无法删除的修复(PR #7421);Swow 下 cookie 失效(PR #7176)。
  • Request::hasFile() 支持 Swow(PR #6056);$request->all() 数字键重置修复(PR #6566)。
  • testing 组件支持 PATCH 方法(PR #7553)。

8.3 Swagger

  • 支持为 swagger 定义 servers 与 info(PR #7149);processors 配置(PR #6338);root path 修复(PR #6987);swagger 服务端补充 content-type 响应头(PR #6360);收集 mediaType request body 的验证规则(PR #6380);swagger 使用 priorityMiddleware 代替 middleware(PR #7537)。

9. 配置中心与注册中心:Nacos、Apollo、Etcd

  • Nacos:支持 aliyun MSE 签名(PR #7648,v3.1.67);SDK 支持 v2/v3 版本(PR #7467,v3.1.61);naming service 支持 gRPC streaming(PR #5586,v3.1.0);provider 不支持 psr4 的修复(PR #7543);Nacos\Application 构造参数名回退(PR #7561);grpc 协议下配置中心失效修复(PR #6352)。
  • Apollo:监听多个 namespace 时不再频繁同步配置(PR #5945)。
  • Etcd:hyperf/config-etcd 组件独立维护于 src/config-etcd。
  • consul:相关实现见 src/consul 与 src/config-zookeeper。

10. 组件级兼容性修复速查

  • AOP:__construct 上 AOP 失效(PR #6828)、Trait 上 AOP 不生效(PR #6909)、可变参数下 AOP 失效(PR #6372)——这三处修复表明 3.1 对代理生成边界做了收敛。
  • Macroable:HttpServer\Response 的 Macroable 失效修复(PR #7731);Macroable::macro() 增加对引用参数的校验(PR #7501);Pipeline 新增 Macroable trait(PR #7492)。
  • Str::is():将 $value 与 $pattern 转为字符串处理(PR #7053)。
  • data_get:支持 int 键(PR #7081)。
  • InteractsWithTime:支持毫秒级系统时间(PR #6990)。
  • 类名缓存:classes cache 无法解码的修复(PR #7712)。

11. 升级检查清单

对照本文内容,从 v3.0 升级到 v3.1.x(或从低版本 3.1 升级到 v3.1.71)时,建议逐项确认:

  1. 运行时基线:PHP >= 8.1、Swoole >= 5.0(v3.1.0 起),并确认 hyperf/engine 已升级到 ^2.0。
  2. 废弃项:检查是否使用 Hyperf\Utils、swoole-tracker、WebSocketHandeShakeException、PgSQLConnection::str_replace_once 等已废弃 API,逐一替换。
  3. 枚举替换:AMQP 的 Result/Message\Type 已改为枚举,字符串比较需同步迁移。
  4. Redis 配置校验:非法 option key 现在会直接抛异常,请校验配置合法性。
  5. 协程计时器:使用 Timer::tick() 的定时任务建议升级到 v3.1.71+,避免 10 秒超时截断;依赖 wait() 行为的代码注意其容器探测逻辑(v3.1.70)。
  6. Kafka 生产可靠性:如需生产重试,配置 produce_retry 与 produce_retry_sleep(默认 3 次、间隔 0.1 秒)。
  7. gRPC 高可用:多实例负载均衡场景可配置 client_count。
  8. 数据库新能力:按需采用 whereJsonContainsKey、sole()、incrementOrCreate()、createOrFirst() 等新方法,并注意 updateOrInsert 返回类型已保证为 boolean。
  9. 配置中心:多 namespace 的 Apollo 用户升级后可获得更稳定的配置同步行为。

12. 延伸阅读

版本日期与 PR 编号均以 docs/en/changelog/3.1.md 原文为准;文中所有组件路径均可直接在仓库中查阅。

登录后查看全文
hyperf