Hyperf v2.1 版本更新全解析:从 Swow 驱动到 RPC 路径生成器的关键演进

原创2026-10-11 18:09:591,917 阅读
文章标签:后端Web框架微服务RPC框架依赖注入服务注册发现配置中心并发编程API网关消息队列

Hyperf v2.1 版本更新全解析:从 Swow 驱动到 RPC 路径生成器的关键演进

本指南基于 Hyperf 官方 v2.1 系列版本更新记录(docs/zh-hk/changelog-v2.1.md)整理而成,覆盖 v2.1.0 至 v2.1.23 共 24 个版本的依赖升级、破坏性变更、新增能力与问题修复,并结合仓库源码剖析 @Crontab 动态开关、DotPathGenerator、withMax 系列聚合方法、Transactional 注解、Waiter 协程等待器等代表性特性。读完本文,你将掌握 v2.1 时代 Hyperf 的能力边界与升级注意事项,并能据此评估、规划从旧版本向 v2.1 迁移的落地细节。

v2.1.0 主线版本:一次全面的基础能力升级

v2.1.0(2020-12-28)是 v2.1 系列的主线版本,集中体现了 Hyperf 对运行时环境与依赖生态的整体升级,其中不少决策直接影响了后续版本的行为与 API 走向。

依赖升级

依赖 版本要求 影响面
php >=7.3 全框架运行环境基线提升
phpunit/phpunit ^9.0 测试体系升级,配合新语法与断言 API
guzzlehttp/guzzle ^6.0|^7.0 HTTP 客户端与协程 Handler 兼容双版本
vlucas/phpdotenv ^5.0 环境变量解析
endclothing/prometheus_client_php ^1.0 指标采集
twig/twig ^3.0 视图引擎
jcchavezs/zipkin-opentracing ^0.2.0 链路追踪
doctrine/dbal ^3.0 数据库抽象层(Migration 依赖)
league/flysystem ^1.0|^2.0 文件系统抽象

注意,league/flysystem 的 ^2.0 支持在后续 v2.1.2 中被撤销——由于 2.0 版本存在兼容问题,官方在 #3077 中将该依赖降级回 ^1.0,升级时应锁定 1.x 分支使用。

破坏性移除(升级必读)

v2.1.0 清理了一批已废弃成员,升级到 v2.1 前请先检查代码中是否仍在使用:

  • Hyperf\Amqp\Builder 中废弃成员变量 $name;
  • Hyperf\Amqp\Message\ConsumerMessageInterface 中废弃方法 consume();
  • Hyperf\AsyncQueue\Driver\Driver 中废弃成员变量 $running;
  • Hyperf\HttpServer\CoreMiddleware 中废弃方法 parseParameters();
  • Hyperf\Utils\Coordinator\Constants 中废弃常量 ON_WORKER_START 与 ON_WORKER_EXIT;
  • Hyperf\Utils\Coordinator 中废弃方法 get();
  • 配置文件 rate-limit.php 被移除,统一改用 rate_limit.php;
  • 无用类 Hyperf\Resource\Response\ResponseEmitter 被移除;
  • hyperf/paginator 从 hyperf/database 的依赖中剥离(需要时单独安装);
  • Hyperf\Utils\Coroutine\Concurrent 中的方法 stats() 被移除。

行为变更

  • Hyperf\Utils\Coroutine::parentId:改为返回父协程的协程 ID。在主协程中调用返回 0;在非协程环境调用抛出 RunningInNonCoroutineException;协程环境已销毁时抛出 CoroutineDestroyedException。
  • Hyperf\Guzzle\CoroutineHandler:删除 execute() 与 checkStatusCode() 方法;initHeaders() 改为返回初始化好的 Header 列表,而非直接赋值到客户端中。
  • PDO 绑定(#2720):不再在 PDOStatement::bindValue() 中设置 data_type,避免字符串索引使用整型时索引无法命中的问题。
  • 流数据读取(#2871):从 StreamInterface 获取数据时改用 (string) $body 而非 $body->getContents(),因为 getContents() 只返回剩余数据而非全部数据。
  • 中间件(#2909):允许设置重复的中间件。
  • 异常格式化(#2935):修改 Exception Formatter 的默认规则。
  • 模型生成(#2979):gen:model 不再自动将 decimal 格式转化为 float,避免精度损失。

即将废弃(提前预告)

  • Hyperf\AsyncQueue\Signal\DriverStopHandler 将于 v2.2 弃用,请改用 Hyperf\Process\Handler\ProcessStopHandler;
  • Hyperf\Server\SwooleEvent 将于 v3.0 弃用,请改用 Hyperf\Server\Event。

新增能力

  • Swow 驱动支持(#2659 / #2663):除 Swoole 外,v2.1 引入 Swow 作为新的协程引擎驱动,同时修复了自定义进程在 Swow 驱动下无法使用的问题(#2741)。
  • 异步队列日志监听器(#2671):新增 Hyperf\AsyncQueue\Listener\QueueHandleListener,用于记录异步队列的运行日志。
  • 协程等待器(#2923):新增 Hyperf\Utils\Waiter,可阻塞等待一个协程结束并获取其结果。
  • 模型集合列提取(#3001):新增 Hyperf\Database\Model\Collection::columns(),行为类似 array_column。
  • JSON 编解码深度控制(#3002):为 Json::decode / Json::encode 新增 $depth 与 $flags 参数。
  • Prometheus 协议扩展(#3009):优化 prometheus 使其同时支持 https 与 http 协议。

源码视角:v2.1 新增核心机制的实现剖析

changelog 只记录结论,这里结合仓库源码还原几个代表性新特性的真实实现,帮助理解其适用场景与边界。

@Crontab 的 enable 参数:从开关到动态调度

v2.1.9 为 Crontab 注解新增 enable 参数用于控制任务是否注册,v2.1.17 进一步支持传入数组实现动态控制(#3329 中,参数类型被声明为 array|bool|string,其解析逻辑位于 parseEnable():

protected function parseEnable(string $className): void
{
    if ($this->enable === 'true') {
        $this->enable = true;
        return;
    }
    if ($this->enable === 'false') {
        $this->enable = false;
        return;
    }
    if (is_string($this->enable)) {
        $this->enable = [$className, $this->enable];
    }
}

可以看到,enable 支持三类写法:布尔值直接开关;字符串会被转换为 [类名, 方法名] 的回调形式;数组则交由注解收集期动态求值。结合 v2.1.13 修复的「@Crontab 无法作用于方法、一个类可配置多个 @Crontab」问题(#3450),当前版本支持在方法上叠加多个定时任务注解,并通过 enable 按配置中心开关动态启停。

RPC 路径生成器:DotPathGenerator 与既有实现

v2.1.19 为 RPC 组件新增 Hyperf\Rpc\PathGenerator\DotPathGenerator(#3626:

public function generate(string $service, string $method): string
{
    $handledNamespace = explode('\\', $service);
    $path = StrCache::studly(end($handledNamespace));
    return $path . '.' . StrCache::studly($method);
}

它生成的是 UserService.getInfo 形式的点分路径,而默认的 src/rpc/src/PathGenerator/PathGenerator.php 则生成 /user/getInfo 形式的斜杠路径(同时会剥离类名末尾的 Service 后缀并转为 snake_case)。两种生成器均实现 Hyperf\Rpc\Contract\PathGeneratorInterface,具体使用哪种由协议管理器在 src/rpc/src/ProtocolManager.php 中的 path-generator 配置项决定,JSON-RPC 的默认实现见 src/json-rpc/src/PathGenerator.php。如果对端服务约定的路径风格不同,可通过该配置切换生成器。

ORM 关系聚合:withMax / withMin / withSum / withAvg

v2.1.15 新增的四个关系聚合方法(#3484,它们统一委托给 withAggregate(),例如:

public function withMax($relation, string $column): static
{
    return $this->withAggregate($relation, $column, 'max');
}

withAggregate() 会在主查询上追加一个子查询 SELECT,将关联表的 MAX/MIN/SUM/AVG 聚合结果作为字段带出,避免 N+1 查询。用法与既有 withCount() 保持一致,例如 Post::withMax('comments', 'score')->get()。

事务注解参数化:$connection 与 $attempts

v2.1.11 为 Hyperf\DbConnection\Annotation\Transactional 增加 $connection 和 $attempts 参数(#3376:

public function __construct(public string $connection = 'default', public int $attempts = 1)

对应的切面 src/db-connection/src/Aspect/TransactionAspect.php 会把注解参数透传给 Db::connection()->transaction():

return Db::connection($transactional->connection)->transaction(
    static function () use ($proceedingJoinPoint) {
        return $proceedingJoinPoint->process();
    },
    $transactional->attempts
);

由此可以按方法粒度指定事务连接池名称(默认为 default)与重试次数,例如 #[Transactional(connection: 'order', attempts: 3)] 表示在 order 连接上执行事务并在死锁时重试 3 次。

协程等待与连接复用:Waiter 与 Channel\Caller

Hyperf\Utils\Waiter(src/coroutine/src/Waiter.php)通过创建一个容量为 1 的 Channel,把闭包投递到新协程执行,再在当前协程 pop 结果;支持超时(默认 10 秒)与异常透传(内部用 ExceptionThrower 包装):

public function wait(Closure $closure, ?float $timeout = null)
{
    $channel = new Channel(1);
    Coroutine::create(function () use ($channel, $closure) { ... });
    $result = $channel->pop($timeout);
    if ($result === false && $channel->isTimeout()) {
        throw new WaitTimeoutException(...);
    }
    ...
}

它是「以同步写法获取异步结果」的通用工具,v2.1.13 与 v2.1.5 相继优化的 Hyperf\Utils\Channel\Caller(src/coroutine/src/Channel/Caller.php)则用于协程安全地复用连接,防止连接被多个协程同时绑定。

反射工具箱:ClassInvoker 与 Pipeline::handleCarry

v2.1.7 新增的 Hyperf\Utils\Reflection\ClassInvoker(src/support/src/Reflection/ClassInvoker.php)通过魔术方法 __get / __call 反射执行对象的非公共方法并读取非公共变量,适合测试与调试场景:

$invoker = new ClassInvoker($service);
$secret = $invoker->secret;      // 读取 private 属性
$result  = $invoker->privateMethod($arg); // 调用 private 方法

同版本新增的 Pipeline::handleCarry(src/pipeline/src/Pipeline.php)返回透传的 $carry 值,子类可覆写它以自定义管道返回值处理逻辑。

逐版本修复与增强记录(v2.1.1 ~ v2.1.23)

以下按版本整理 v2.1 系列的补丁内容,完整继承官方记录。

v2.1.23 - 2021-07-12

  • 优化 JSON RPC 服务,优先初始化 PSR Response,避免 PSR Request 初始化失败后无法从上下文中获取 Response 的问题(#3787)。

v2.1.22 - 2021-06-28

安全性更新

  • 修复验证器规则 active_url 无法正确检查 dns 记录,导致可绕过验证的问题(#3723)。
  • 修复可利用 RequiredIf 规则生成反序列化漏洞小工具链的问题(#3724)。

修复

  • 修复验证器规则 in / not in 判断有误:例如规则为 in:00 时,0 不应被允许通过(#3721)。

v2.1.21 - 2021-06-21

  • 修复使用熔断器时,成功次数与失败次数的界限判断错误的问题(#3684)。

v2.1.20 - 2021-06-07

修复

  • 修复形如 10-12/1,14-15/1 的定时任务规则无法使用的问题(#3667)。
  • 修复没有反斜线、形如 10-12 的定时任务规则无法使用的问题(#3669)。
  • 修复 @Task 注解中 $workerId 参数无法正常使用的问题(#3674)。

优化

  • 优化 AbstractServiceClient::getNodesFromConsul(),排除找不到端口的隐患(#3663)。
  • 优化 Guzzle 组件 CoroutineHandler 代理相关代码,增强兼容性(#3668)。

v2.1.19 - 2021-05-31

修复

  • 修复相同路径但不同实现逻辑的路由,会在 describe:routes 命令中被合并成一条的问题(#3618)。
  • 修复 Hyperf\Di\Annotation\Scanner 中无法正常使用 class_map 功能的问题(#3625)。

新增

  • 为 RPC 组件新增路径打包器 Hyperf\Rpc\PathGenerator\DotPathGenerator(#3626)。

新组件孵化

  • nacos-sdk:基于 Nacos Open API 实现的 SDK。

v2.1.18 - 2021-05-24

修复

  • 修复事务回滚时,模型累加、累减操作导致模型缓存产生脏数据的问题(#3598)。
  • 修复协程风格 WebSocket 服务中,onOpen 事件无法在事件结束后销毁协程的问题(#3607)。
  • 修复数据库存在前缀时,fromSub() 与 joinSub() 无法正常使用的问题(#3610)。

v2.1.17 - 2021-05-17

修复

  • 修复 Swow 服务处理 keepalive 请求时,协程无法在每个请求后结束的问题(#3586)。

新增

  • @Crontab 注解的 enable 参数支持设置数组,可动态控制定时任务是否启动(#3329)。

v2.1.16 - 2021-04-26

修复

  • 修复 consul 无法将节点强制离线的问题(#3510)。
  • 修复 Nats 因 Socket 超时时间小于最大闲置时间导致连接意外关闭的问题(#3513)。
  • 修复 @Inject 无法作用于嵌套 Trait 的问题(#3520)。

新增

  • 新增方法 Hyperf\HttpServer\Request::clearStoredParsedData()(#3514:当上下文中存在已解析数据时将其置空,用于清理缓存的解析结果。

优化

  • 优化 Hyperf\Di\Aop\PropertyHandlerTrait(#3517)。

v2.1.15 - 2021-04-19

  • 新增 ORM 方法 withMax()、withMin()、withSum()、withAvg()(#3484)。

v2.1.14 - 2021-04-12

修复

  • 修复协程风格下 WebSocket 服务不支持配置多个端口的问题(#3465)。
  • 修复协程风格下 WebSocket 服务无法正常释放连接池的问题(#3467)。

新增

  • 新增方法 Sender::getResponse()(#3472:
public function getResponse(int $fd): mixed
{
    return $this->responses[$fd] ?? null;
}

v2.1.13 - 2021-04-06

修复

  • 修复 SocketIO 服务定时清理失效 fd 的功能无法作用到其他 worker 进程的问题(#3432)。
  • 修复 RPC 结果不支持允许为 null 的类型,例如 ?array 会被强制转为数组(#3434)。
  • 修复模型缓存中因存在表前缀导致模型默认值无法生效的问题(#3447)。
  • 修复 @Crontab 注解无法作用于方法的问题,支持一个类中配置多个 @Crontab(#3450)。

优化

  • 优化 Hyperf\Utils\Channel\Caller 回收实例的机制,防止实例为 null 时无法正确回收(#3453)。
  • 优化 phar:build 脚本,支持以软连接方式加载的组件包(#3455)。

v2.1.12 - 2021-03-29

修复

  • 修复 worker_num 设置为非 Integer 时,定时任务 Task 策略无法正常使用的问题(#3423)。
  • 修复为可选参数路由设置中间件时,中间件被意外执行两次的问题(#3426)。

优化

  • 优化 co-phpunit 的代码(#3422)。

v2.1.11 - 2021-03-22

新增

  • 为 Hyperf\DbConnection\Annotation\Transactional 增加 $connection 与 $attempts 参数(#3376)。
  • 新增 Hyperf\Testing\Client::sendRequest()(#3403,它在独立协程中通过 wait() 执行请求,避免协程变量污染。

修复

  • 修复超全局变量在协程上下文里没有 Request 对象时无法正常工作的问题(#3380)。
  • 修复使用 @Inject 注入的对象会被 trait 中注入的对象覆盖的问题(#3394)。
  • 修复继承使用 @Inject 注入私有变量的父类时,子类实例化报错的问题(#3395)。
  • 修复单元测试中 UploadedFile::isValid() 无法正确判断结果的问题(#3398)。

v2.1.10 - 2021-03-15

修复

  • 修复 Arr::forget 在 key 为 integer 且不存在时执行报错的问题(#3348)。
  • 修复 hyperf/validation 中 FormRequest 无法从协程上下文获取修改后的 ServerRequest,导致验证失败的问题(#3351)。
  • 修复 hyperf/testing 客户端 Hyperf\Testing\Client 无法模拟构造正常 UriInterface 的问题(#3356)。
  • 修复入口文件 bin/hyperf.php 中自定义的常量无法在 server:watch 命令中使用的问题(#3363)。
  • 修复协程风格服务在未配置 pid_file 时仍意外生成 runtime/hyperf.pid 文件的问题(#3365)。

优化

  • 优化 phar:build:可在不使用 php 脚本的情况下直接执行 phar 文件,如同执行 ./composer.phar 而非 php composer.phar(#3364)。
  • 优化 gen:model 生成字段类型注释时,尽量读取自定义转换器转换后的对象类型(#3367)。

v2.1.9 - 2021-03-08

修复

  • 修复 JsonEofPacker 无法正确解包自定义 eof 数据的问题(#3326)。
  • 修复因其他协程修改静态变量 $constraints 导致模型关系查询错误的问题(#3330)。

新增

  • 为 Crontab 注解增加 enable 参数,用于控制当前任务是否注册到定时任务中(#3325)。

优化

  • 优化 testing 组件,使模拟请求的方法运行在独立协程中,避免协程变量污染(#3338)。

v2.1.8 - 2021-03-01

修复

  • 修复 hyperf/cache 在注解中未设置超时时间时,将超时时间强制转为 0 导致缓存不失效的问题(#3301)。

新增

  • 新增 Blueprint::comment(),允许在 Migration 中设置表注释(#3310,用法为 Schema::create('table', function (Blueprint $table) { $table->comment('表注释'); ... });。
  • 新增 RouteCollector::getRouteParser,可方便地从 RouteCollector 获取 RouteParser 对象(#3311)。
  • 允许在 hyperf/db 组件中注册自定义数据库适配器(#3316)。

优化

  • 优化 WebSocket 服务找不到对应路由时直接返回响应(#3308)。
  • 优化从连接池获取连接的代码逻辑,避免因重写低频组件报错导致连接被意外丢弃(#3319)。

新组件孵化

  • rpc-multiplex:基于 Channel 实现的多路复用 RPC 组件。
  • db-pgsql:适配 hyperf/db 的 PgSQL 适配器。

v2.1.7 - 2021-02-22

修复

  • 修复使用 doctrine/dbal 修改数据库字段名报错的问题(#3272)。

新增

  • 新增 Pipeline::handleCarry,方便处理返回值(#3261)。
  • 新增 Hyperf\Utils\Reflection\ClassInvoker,用于执行非公共方法和读取非公共变量(#3267)。
  • 为 kafka 消费者新增订阅多个主题的能力(#3268)。
  • 为 phar:build 新增选项 -M,可将外部文件或目录映射到 Phar 包中(#3193 / #3296)。

变更

  • 为不同的 kafka 消费者设置不同的 Client ID(#3258)。
  • hyperf/signal 将拼写错误的 stoped 修正为 stopped(#3282)。

v2.1.6 - 2021-02-08

修复

  • 修复 AMQP 组件因连接服务端失败导致连接池耗尽的问题(#3233)。
  • 修复 hyperf/kafka 设置 autoCommit 为 false 无效的问题(#3245)。
  • 修复 Nsq 消费者进程无法触发 defer 方法的问题(#3255)。

优化

  • 优化 hyperf/kafka 重用连接进行消息发布(#3249)。

移除

  • 移除 hyperf/kafka 的 rebalance 检查,因为底层库 longlang/phpkafka 已增加对应检查(#3235)。

v2.1.5 - 2021-02-01

修复

  • 修复 hyperf/rpc-server 中中间件被意外替换的问题(#3204)。
  • 修复 hyperf/amqp 在协程风格服务中因超时意外报错时无法正常回收到连接池的问题(#3209)。
  • 修复 hyperf/database 中 JOIN 查询导致内存泄露的问题(#3222)。
  • 修复 hyperf/tracer 在 defer 中调用 flush 失败时导致进程异常退出的问题(#3228)。
  • 修复 hyperf/scout 中 orderBy 方法无效的问题(#3230)。

新增

  • 为 hyperf/nacos 添加配置项 url,用于访问 Nacos 服务(#3211)。
  • 新增 Hyperf\Utils\Channel\Caller,允许协程安全地使用连接,避免连接被多个协程绑定导致报错(#3214)。
  • 新增 Hyperf\Utils\CodeGen\Package::getPrettyVersion(),允许获取组件版本(#3224,内部委托 Jean85\PrettyVersions::getVersion(),取不到版本时返回 unknown。

变更

  • 默认为 AMQP 配置 QOS 参数:prefetch_count 为 1、global 为 false、prefetch_size 为 0(#3218 中有对应实现:
protected ?array $qos = [
    'prefetch_size' => 0,
    'prefetch_count' => 1,
    'global' => false,
];
  • 升级 jean85/pretty-package-versions 至 ^1.2|^2.0,支持 Composer 2.x(#3224)。注意:使用 Composer 2.x 需安装 ^2.0 版本,反之安装 ^1.2 版本。

优化

  • 优化 hyperf/database:使用 group by 或 having 时执行子查询获得总数(#3226)。

v2.1.4 - 2021-01-25

修复

  • 修复 Hyperf\Database\Schema\MySqlBuilder::getColumnListing 在 MySQL 8.0 中无法正常使用的问题(#3165)。
  • 修复 hyperf/database 中 where 语句因代码编写不严谨,导致绑定参数被恶意替换的问题(#3174)。
  • 修复 json-rpc 客户端因对端服务重启导致接收数据一直异常的问题(#3179)。
  • 修复 kafka 在集群模式下无法正常使用的问题(#3189)。
  • 修复 json-rpc 客户端因对端服务重启导致连接池连接全部失效、新请求首次使用皆报错的问题(#3191)。

新增

  • 为 hyperf/watcher 新增更友好的驱动器 FindNewerDriver,支持 Mac、Linux 和 Docker(#3170)。
  • 为 JsonRpcPoolTransporter 新增重试机制:连接、发包、收包失败时默认重试 2 次,收包超时不重试(#3195)。

优化

  • 优化 ErrorExceptionHandler 中与 set_error_handler 相关的入参代码,解决静态检测因入参不匹配报错的问题(#3169)。
  • 优化 hyperf/json-rpc:连接中断后先尝试重连(#3191)。

变更

  • 严格检查 hyperf/database 中 where 语句绑定参数(#3174)。

新组件孵化

  • DAG:轻量级有向无环图任务编排库。
  • RPN:逆波兰表示法(表达式求值)。

v2.1.3 - 2021-01-18

修复

  • 修复 tracer 组件无法正常使用的问题(#3070)。
  • 修复从已被销毁的协程中复制协程上下文时导致报错的问题(#3106)。
  • 修复使用 describe:routes 命令时相同 callback 不同路由组的路由被替换覆盖的问题(#3108)。
  • 修复 migrations 配置名位置错误的问题(#3118)。
  • 修复 Swoole 扩展 v4.6 中 SWOOLE_HOOK_SOCKETS 与 jaeger 冲突的问题(#3126)。
  • 修复 database 组件未主动设置 PDO::ATTR_PERSISTENT 为 true 时导致的类型错误(#3137)。
  • 修复使用 Migration 时 doctrine/dbal 无法正常工作的问题(#3141)。

新增

  • 为 view-engine 组件增加合并任意标签的能力(#3059)。
  • 为 view-engine 组件增加 ComponentAttributeBag::has() 方法(#3123)。

v2.1.2 - 2021-01-11

修复

  • 修复 increment() 后使用 save() 导致 extra 数据被保存两次的问题(#3050)。
  • 修复 hyperf/db 在 defer 中使用时导致连接被其他协程绑定的问题(#3082)。
  • 修复 phar 打包后 getRealPath 无法正常工作的问题(#3084)。
  • 修复使用 AOP 时 pipeline 导致内存泄露的问题(#3087)。
  • 修复 hyperf/scout 中 ElasticsearchEngine::getTotalCount() 无法兼容 Elasticsearch 7.0 的问题(#3095)。

新增

  • 新增 hyperf/kafka 组件(#2847 目录,包含 Producer、ConsumerManager、AbstractConsumer 等核心类。
  • 为 hyperf/db 新增 ConnectionInterface::run(Closure $closure) 方法(#3066)。

优化

  • 打包 phar 时优化重写 scan_cacheable 的代码(#3046)。

变更

  • 因 league/flysystem 2.0 无法兼容,降级到 ^1.0(#3077)。

v2.1.1 - 2021-01-04

修复

  • 修复 database 组件未主动设置 PDO::ATTR_PERSISTENT 为 true 时导致的类型错误(#3045)。
  • 修复 socketio-server 为 sid 续约时报错的问题(#3047)。
  • 修复 grpc-server 入参无法被正确解析的问题(#3062)。

新增

  • 为 metric 组件新增收集命令行指标的功能(#3052)。
  • 为 socketio-server 新增 Engine::close 协议支持,并在调用 getRequest 失败时抛出连接已被关闭的异常(#3054)。

升级到 v2.1 的注意事项汇总

综合 v2.1 全系列变更,从旧版本升级时建议按以下清单自查:

  1. PHP 版本:确认运行环境满足 php >= 7.3;若使用 Composer 2.x,需将 jean85/pretty-package-versions 升级到 ^2.0(#3224)。
  2. 清理废弃 API:v2.1.0 移除的成员(见上文「破坏性移除」清单)需逐一替换;DriverStopHandler、SwooleEvent 虽未立即删除,但已被预告弃用,应提前迁移。
  3. 行为差异:Coroutine::parentId() 的返回值与异常语义、CoroutineHandler::initHeaders() 的返回方式、(string) $body 读取流数据、gen:model 不再自动转换 decimal 为 float、允许配置重复中间件等,均属于可能影响既有代码的行为变更。
  4. 配置文件:rate-limit.php 更名为 rate_limit.php;migrations 配置位置已修正(#3118)。
  5. 依赖锁定:league/flysystem 保持在 ^1.0;phpunit 升级到 ^9.0 后需同步更新测试代码。
  6. 安全补丁:建议至少升级到 v2.1.22 以获取 active_url DNS 校验与 RequiredIf 反序列化漏洞修复(#3723 / #3724)。

总结

v2.1 系列是 Hyperf 在 2020 年末至 2021 年中承上启下的重要版本线:主线 v2.1.0 完成了 PHP 7.3+ 基线、Swow 驱动接入、JSON 编解码扩展与一批废弃 API 的清理;随后的 22 个补丁版本围绕定时任务(@Crontab 动态 enable)、RPC 路径生成、ORM 关系聚合、事务注解参数化、AMQP QoS 默认值、Kafka 集群与多主题订阅、Phar 打包等高频使用场景持续加固。本文所有源码级结论均可在仓库对应文件中复核,升级实践中建议对照官方更新记录逐条确认涉及自身业务的变更点。

登录后查看全文
hyperf