后端微服务【免费下载链接】hyperf A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.项目地址https://gitcode.com/gh_mirrors/hy/hyperf点击查看免费下载本文以官方 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.03.1 分支的基线版本v3.1.02023-12-01是 3.1 系列的第一个正式版本本节的变更决定了整个 3.1 分支的运行时基线升级到 3.1.x 的开发者应首先核对这里的依赖与环境要求。1.1 依赖基线升级v3.1.0 对运行环境提出了更高的要求依赖项3.1.0 要求说明PHP8.1低于 8.1 的 PHP 版本不再受支持Swoole5.0不再支持 Swoole 4.x见 3.1.0 Removed 条目hyperf/engine^2.0底层协程引擎随之升级phpunit/phpunit^10.0测试框架基线同步升级同时3.1.0 增加了对Swow协程引擎的适配reactive-x与socketio-server两个组件开始支持 SwowPR #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/carbonv3.1.14 加入与hyperf/migration-generator用于从数据库反向生成迁移文件PR #5967。1.3 命令系统AsCommand 注解与 ClosureCommandPR #5930、#5934 引入了AsCommand注解与ClosureCommand让定义命令不再必须继承Hyperf\Command\Commanduse 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、#5926Query\Builder新增toRawSql()PR #5898Database\Connection新增getRawQueryLog()PR #5906。辅助函数新增data_forget()PR #5915、Str::isUrl()PR #5914、Arr::isList()PR #5918。缓存hyperf/cache注解新增skipCacheResultsPR #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 Balancerjson-rpc http transporter 在状态码不是 200 时不再从负载均衡节点列表移除该节点PR #5943。AMQPHyperf\Amqp\Result与Hyperf\Amqp\Message\Type由class改为enumPR #5961如果你的业务代码用字符串常量与之比较需要迁移为枚举比较。config 组件多级目录配置可通过config(a.c)读取autoload/a/c.php中的内容PR #6128。废弃清理移除了Hyperf\Utils中未使用的代码与过期方法、swoole-tracker组件PR #6244、Hyperf\Coroutine\Traits\ContainerPR #6043等。Base62 解码Base62::decode()解码非法数据时抛出InvalidArgumentException而非TypeErrorPR #6022。2. 数据库层演进从查询构建器到 Schema 蓝图3.1 系列在hyperf/database上持续投入绝大多数新增方法都能在 src/database/src 中找到对应实现。2.1 Query\Builder 的查询能力扩展按时间顺序Query Builder 新增了大量方法条件查询whereAll/orWhereAll、whereAny/orWhereAnyPR #6767v3.1.23whereNone/orWhereNonePR #7015v3.1.37whereJsonContainsKey等 4 个 JSON 键判断方法PR #7699v3.1.66。JSON 查询whereJsonOverlaps、orWhereJsonOverlaps、whereJsonDoesntOverlapPR #6782v3.1.23。Lateral Join支持 SQL 的 Lateral Join 写法PR #6774v3.1.23。索引提示useIndex、forceIndex、ignoreIndexPR #6740v3.1.21。批量更新incrementEach/decrementEachPR #6792v3.1.24。排序重设reorder()清除并重设排序PR #7016v3.1.38。位运算支持where bit functions and operatorsPR #6950v3.1.32。存在性判断existsOr/doesntExistOrPR #7259v3.1.51、sole()PR #7260v3.1.51查询必须恰好返回一条记录。值区间Grammar 层新增whereValueBetween()PR #7518v3.1.61。插入忽略insertOrIgnoreUsingPR #6783v3.1.23updateOrInsert空输入问题修复PR #6818。SQL 解释explain()PR #6746v3.1.22。2.2 模型与 Eloquent 风格方法创建/更新incrementOrCreate()PR #7480v3.1.61、updateOrFail()PR #6884v3.1.27、createOrFirst()与createOrRestore()PR #7255v3.1.51读取null时抛出异常的行为变化见 PR #7291、discardChanges()PR #7261。查询辅助findOr()PR #7143v3.1.45、findOrFail()加入Model\CollectionPR #7192v3.1.48、valueOrFail()PR #6820、touch()更新时间戳PR #6814、except()PR #7486、qualifyColumns()PR #6815。软删除isSoftDeletable()PR #7484v3.1.61。关系查询whereRelation/orWhereRelationPR #6844、withWhereHas()PR #6837、whereMorphRelation/orWhereMorphRelationPR #6878、orHasMorph/orDoesntHaveMorphPR #6851。属性隐藏/显示makeHiddenIf/makeVisibleIfPR #6858。分块与懒加载chunkById/chunkByIdDescPR #6846、eachByIdPR #6876其 bug 修复见 PR #7705、lazyPR #6866、lazyById/lazyByIdDescPR #6822、chunkMap()PR #6821。游标分页cursor paginator 于 v3.1.25 引入PR #6809getOriginalColumnNameForCursorPagination的修复见 PR #7738。Cast 扩展AsArrayObjectPR #7487、AsCollectionPR #7607、枚举互转v3.1.0。连接层Connection::scalar()取首行首列PR #7200v3.1.52连接内置错误计数异常过多时自动重置连接PR #6085。2.3 Schema 构建器的演进Schema 相关能力在 3.1 中大幅增强集中在 src/database/src/Schema 目录元数据查询Schema::getTables()PR #6845、Schema::getForeignKeys()PR #7059、Schema::whenTableHasColumn/whenTableDoesntHaveColumnPR #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/nullableNumericMorphsPR #7063。外键定义ForeignKeyDefinition新增cascadeOnDelete()、restrictOnDelete()、noActionOnDelete()、restrictOnUpdate()、nullOnUpdate()、noActionOnUpdate()PR #7693Blueprint::foreign()的返回类型修复解决了链式调用references()、on()时的静态分析报错PR #7682。数据库级操作createDatabase/dropDatabaseIfExistsPR #6825Builder::withoutForeignKeyConstraints()PR #7684。2.4 数据库相关修复盘点PostgreSQLmigrate: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。SQLitedatabase-sqlite组件于 v3.1.10 加入PR #6533sqlite 迁移失效修复见 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、#7764v3.1.70Timer::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.phpWaiter::wait()内部通过Channel(1)Coroutine::create把闭包投递到子协程执行。因此在使用 v3.1.70 及更早版本的tick()执行耗时回调时如果回调超过 10 秒会被超时中断升级到 v3.1.71 后不再受该默认超时影响。3.2 新增并发原语Hyperf\Coroutine\BarrierPR #7343v3.1.54继承自Hyperf\Engine\Barrier见 src/coroutine/src/Barrier.php用于等待一组协程全部完成。Hyperf\Coroutine\MutexPR #7224v3.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在超时或通道关闭时返回falseunlock超过popTimeout说明重复解锁返回false。Hyperf\Coroutine\WaitConcurrentPR #7263v3.1.51在Concurrent并发限制的基础上叠加WaitGroupcreate()时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 #7286v3.1.52列出当前进程内所有协程。3.3 Redis 连接与协程锁修复v3.1.59PR #7394使用带回调的transaction或pipeline时连接立即释放回连接池。v3.1.69PR #7734修复长时间运行环境下Redis::pipeline()的内存泄漏。v3.1.69PR #7736RedisDriver::keys()在sMembers返回非数组时仍返回数组的修复。v3.1.63PR #7554Redis 集群在未配置 auth 或 auth 为 null 时参数上下文失效的修复。v3.1.57PR #7420Redis 服务重启后 luasha 失效的修复。Redis 相关代码可参考 src/redis/src 下的Redis.php、RedisProxy.php与RedisFactory.php。4. 验证、集合与字符串工具链4.1 验证规则hyperf/validation3.1 系列为验证组件新增了大量规则与方法新规则contains、extensions、hex_colorPR #7313v3.1.53、listPR #6811v3.1.25、prohibitiPR #6885v3.1.28decimal与size组合修复PR #6482。exists/unique 支持模型名验证规则exists与unique支持直接使用App\\Model\\User这类模型类名PR #7459v3.1.67。场景规则重写支持按场景重写验证规则PR #7469v3.1.62。排除规则新增exclude规则PR #7148v3.1.46exclude不生效的修复见 PR #7427v3.1.59。缺失规则回退v3.1.64 修复了验证规则未定义时的 BC 问题PR #7596。兼容性ValidationRuleParser::parseParameters()支持 PHP 8.4PR #7536validateMultipleOf()兼容最新版brick/mathPR #7791。其余方法补充accepted_if、ascii、date_equals等缺失规则消息PR #7150。4.2 集合与数组工具hyperf/collection组件新增的方法覆盖 src/collection/srcArrshuffleAssocPR #7141、sole()PR #7600、push()/array()PR #7500、hasAll()PR #7502、removePR #6471v3.1.6。Collectionreplace()/replaceRecursive()PR #6501、unshiftPR #6738、getOrPut/getOrSetPR #6784、doesntContainStrict()PR #7481、before()/after()PR #6869、sortByMany相关修复PR #6925、#7124。LazyCollectionv3.1.23 引入PR #6757splitIn()类型提示修复PR #6848。4.3 字符串与 FluentStrchopStart()/chopEnd()PR #6917、apa()PR #6576、trim 系列方法PR #6652、numbers()与fromBase64()PR #6799、Str::trim默认规则修复PR #7068。FluentInteractsWithDatatraitPR #7476、isEmpty/isNotEmpty/getIteratorPR #7466。5. 消息队列与 RPCAMQP、Kafka、JSON-RPC 与 gRPC5.1 AMQPhyperf/amqp连接名参数新增connection_name参数用于指定 AMQP 连接名PR #7233v3.1.50。路由键数组Consumer注解的routingKey支持数组PR #6778。交换器自动声明生产消息时自动声明交换器PR #6696消费者消息的交换器声明优化PR #6716、#6717。消息类型Message::getTypeString()避免属性与 getter 方法冲突PR #7741ConsumerMessage::getQueue返回类型修复PR #6635。5.2 Kafkahyperf/kafka生产者重试配置新增produce_retry与producer_retry_sleep配置项PR #7473v3.1.60默认值见 src/kafka/publish/kafka.phpreturn [ // ... produce_retry 3, // 生产失败重试次数 produce_retry_sleep 0.1, // 每次重试间隔秒 ];事件新增Hyperf\Kafka\Event\FailToAck与FailToRequeuePR #7585v3.1.65ConsumerManager新增BeforeLongLangConsumerCreated与AfterConsumerConfigCreated事件PR #6897、#6899。消费策略新增KafkaStrategy::STICKY_ASSIGNOR常量PR #7499v3.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、HostReaderInterfacePR #6504、回调错误处理PR #6668。5.4 gRPC 客户端多客户端负载均衡新增client_count选项可创建多个 gRPC 客户端以配合负载均衡PR #7667、#7672v3.1.66相关实现见 src/grpc-client/src/BaseClient.php。ping 方法gRPC 客户端支持ping()PR #6373。6. 命令、进程与开发工具链6.1 命令组件hyperf/commandAsCommand支持静态方法PR #6978v3.1.34新增命令queue:dynamic-reloadPR #6979v3.1.34。命令选项自动补全为 AsCommand 与 ClosureCommand 提供选项补全PR #6734。新增Hyperf\Command\Concerns\ProhibitabletraitPR #7265v3.1.51用于标记禁止运行的命令。命令异常错误信息优化PR #6962命令在 finally 块中恢复 coordinatorPR #7545v3.1.62。Console::command()增加param-closure-this注解提升 IDE 支持PR #7611v3.1.64。6.2 代码生成与 watcher生成器 --path 选项v3.1.66 起生成命令支持--path指定自定义输出位置PR #7670。gen:model支持从 trait 生成注释PR #7279自动生成属性注释中的usePR #6435、#6437RewriteReturnType注解用于重写返回类型PR #6426支持在编辑器cursor处自动打开新文件PR #7273。gen:constant新增type选项可选const或enumPR #6681。watcher支持在监听时重载.envPR #6936使用PHP_BINARY作为默认 PHP 二进制路径PR #6661修复php路径含空格的问题PR #7424phar:build打包速度优化与declare主文件破坏修复PR #7040、#7034FswatchDriver空读取不再触发重启PR #6686。6.3 进程与池连接池新增Pool::flushAll()与PoolFactory::flushAll()一次性关闭所有连接PR #7698v3.1.66连接释放事件PR #6613v3.1.15。进程ProcessManager的running状态更清晰PR #6172。非协程 task worker新增UnsetContextInTaskWorkerListener用于清理连接上下文PR #6431v3.1.5。7. 缓存、限流、日志与可观测性7.1 缓存hyperf/cache新驱动MemoryDriverPR #6542v3.1.10、SqliteDriverPR #6562v3.1.11。Redis 实例选择支持cache.*.options.pool选择 redis 连接池实例PR #6891。修复内存驱动默认 ttl 不生效PR #7703CacheAHead默认 ttl 问题PR #7109setMultiple内存驱动失效PR #7410。缓存预取优化CacheAheadAspect在另一个协程中写缓存不再阻塞当前协程PR #6608CacheAHead新增runAsync参数PR #7404。7.2 限流hyperf/rate-limit新增配置rate_limit.storage.options.expired_timePR #6795v3.1.24。存储切换器改进PR #6301RateLimitAnnotationAspect::getWeightingAnnotation()在配置rate_limit.storage时失效的修复PR #6374。7.3 日志与追踪logger支持 callable 类型的日志配置PR #7365v3.1.55handler 定义简化PR #5973新增Hyperf\Framework\Logger\ConsoleLoggerPR #7028v3.1.38并支持在 watcher 中运行PR #7033。tracer将请求体与响应体加入追踪PR #6793v3.1.24客户端标签优化PR #7676HttpClientFactory的Content-Type类型由int修正为stringPR #7791。8. WebSocket、Web 与 Swagger8.1 WebSocketwebsocket-client支持设置请求头PR #6632push/disconnect返回结果PR #6648关闭帧丢失修复PR #7318。websocket-server新增日志记录器PR #6665WebSocketHandeShakeException废弃改用WebSocketHandShakeExceptionPR #6621websocket sender支持 SwowPR #6961无效消息处理器导致 fatal exception 修复PR #7231。socketio-serverSwow 引擎支持修复PR #6953带?无 query 的数据解析修复PR #6689。8.2 Web 与 HTTP#[AutoController]提供默认方法可新增options方法配合 CORS 中间件PR #6998v3.1.36。Cookie分区支持PR #6971SetCookie::fromString类型校验修复PR #6836cookie 值为时无法删除的修复PR #7421Swow 下 cookie 失效PR #7176。Request::hasFile()支持 SwowPR #6056$request-all()数字键重置修复PR #6566。testing 组件支持PATCH方法PR #7553。8.3 Swagger支持为 swagger 定义servers与infoPR #7149processors配置PR #6338root path 修复PR #6987swagger 服务端补充content-type响应头PR #6360收集 mediaType request body 的验证规则PR #6380swagger 使用priorityMiddleware代替middlewarePR #7537。9. 配置中心与注册中心Nacos、Apollo、EtcdNacos支持 aliyun MSE 签名PR #7648v3.1.67SDK 支持 v2/v3 版本PR #7467v3.1.61naming service 支持 gRPC streamingPR #5586v3.1.0provider 不支持 psr4 的修复PR #7543Nacos\Application构造参数名回退PR #7561grpc 协议下配置中心失效修复PR #6352。Apollo监听多个 namespace 时不再频繁同步配置PR #5945。Etcdhyperf/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 对代理生成边界做了收敛。MacroableHttpServer\Response的 Macroable 失效修复PR #7731Macroable::macro()增加对引用参数的校验PR #7501Pipeline新增MacroabletraitPR #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时建议逐项确认运行时基线PHP 8.1、Swoole 5.0v3.1.0 起并确认hyperf/engine已升级到^2.0。废弃项检查是否使用Hyperf\Utils、swoole-tracker、WebSocketHandeShakeException、PgSQLConnection::str_replace_once等已废弃 API逐一替换。枚举替换AMQP 的Result/Message\Type已改为枚举字符串比较需同步迁移。Redis 配置校验非法 option key 现在会直接抛异常请校验配置合法性。协程计时器使用Timer::tick()的定时任务建议升级到 v3.1.71避免 10 秒超时截断依赖wait()行为的代码注意其容器探测逻辑v3.1.70。Kafka 生产可靠性如需生产重试配置produce_retry与produce_retry_sleep默认 3 次、间隔 0.1 秒。gRPC 高可用多实例负载均衡场景可配置client_count。数据库新能力按需采用whereJsonContainsKey、sole()、incrementOrCreate()、createOrFirst()等新方法并注意updateOrInsert返回类型已保证为boolean。配置中心多 namespace 的 Apollo 用户升级后可获得更稳定的配置同步行为。12. 延伸阅读3.2 分支变更docs/en/changelog/3.2.md3.0 分支变更docs/en/changelog/3.0.md。其余历史版本docs/en/changelog/2.2.md、docs/en/changelog/2.1.md、docs/en/changelog/2.0.md、docs/en/changelog/1.1.md、docs/en/changelog/1.0.md。组件源码数据库能力可深入 src/database/src协程原语可深入 src/coroutine/src定时器实现见 src/coordinator/src/Timer.php。官方发布历史仓库根目录下的 CHANGELOG.md 与 CHANGELOG-3.1.md。版本日期与 PR 编号均以 docs/en/changelog/3.1.md 原文为准文中所有组件路径均可直接在仓库中查阅。赞分享后端微服务【免费下载链接】hyperf A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.项目地址https://gitcode.com/gh_mirrors/hy/hyperf点击查看免费下载相关推荐Hyperf 3.1 版本线演进全解析从 v3.1.0 到 v3.1.73 的关键能力、修复与升级实践Hyperf 3.1 版本线演进全解析从 v3.1.0 到 v3.1.73 的关键能力、修复与升级实践 Hyperf 3.1 是该项目在 2023 年 12后端Web框架微服务RPC框架异步编程Hyperf 3.1 全版本演进深度解析从 v3.1.0 到 v3.1.72 的能力升级、破坏性变更与源码印证Hyperf 3.1 全版本演进深度解析从 v3.1.0 到 v3.1.72 的能力升级、破坏性变更与源码印证 本文基于 Hyperf 官方 3.1 系列变更后端Web框架微服务RPC框架异步编程Stable-Baselines3 版本演进全解析从 0.1.0 到 2.9.0 的关键变更、破坏性更新与升级指南Stable Baselines3 版本演进全解析从 0.1.0 到 2.9.0 的关键变更、破坏性更新与升级指南 导读 Stable Baselines3人工智能强化学习机器学习上一篇YUI3模块化架构揭秘深入理解Loader与依赖管理系统 下一篇如何快速理解Refit自动生成代理类的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考