Hyperf v2.1 版本更新全解析:从 Swow 驱动到 RPC 路径生成器的关键演进
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
安全性更新
修复
- 修复验证器规则
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
修复
新增
- 新增方法
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
修复
优化
- 优化
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
修复
新增
- 为
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)。
优化
新组件孵化
- 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)。
变更
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)。
新组件孵化
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)。
新增
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/flysystem2.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 全系列变更,从旧版本升级时建议按以下清单自查:
- PHP 版本:确认运行环境满足
php >= 7.3;若使用 Composer 2.x,需将jean85/pretty-package-versions升级到^2.0(#3224)。 - 清理废弃 API:v2.1.0 移除的成员(见上文「破坏性移除」清单)需逐一替换;
DriverStopHandler、SwooleEvent虽未立即删除,但已被预告弃用,应提前迁移。 - 行为差异:
Coroutine::parentId()的返回值与异常语义、CoroutineHandler::initHeaders()的返回方式、(string) $body读取流数据、gen:model不再自动转换decimal为float、允许配置重复中间件等,均属于可能影响既有代码的行为变更。 - 配置文件:
rate-limit.php更名为rate_limit.php;migrations配置位置已修正(#3118)。 - 依赖锁定:
league/flysystem保持在^1.0;phpunit升级到^9.0后需同步更新测试代码。 - 安全补丁:建议至少升级到 v2.1.22 以获取
active_urlDNS 校验与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 打包等高频使用场景持续加固。本文所有源码级结论均可在仓库对应文件中复核,升级实践中建议对照官方更新记录逐条确认涉及自身业务的变更点。