Hyperf 1.1 版本演进全解析：从异步队列到自定义模型转换的 32 次迭代

导读

本文基于 Hyperf 官方仓库的 docs/zh-tw/changelog/1.1.md 版本记录，系统梳理 Hyperf 1.1 系列从 v1.1.0（2019-10-08）到 v1.1.32（2020-05-21）的完整演进脉络。1.1 是 Hyperf 由 1.0 走向成熟的标志性版本线：异步队列注解化、表单验证器、Session、Filesystem、NSQ 等新组件在这一时期集中落地，同时 ORM、RPC、AMQP、模型缓存等核心能力经历了大量缺陷修复与最佳化。阅读本文，你将掌握 1.1 系列每个版本的新增能力与破坏性变更，理解 @AsyncQueueMessage、@Transactional、模型自定义类型转换等特性背后的源码实现，并能在升级或选型时快速定位各能力的引入版本。

一、v1.1.0：1.1 系列的奠基版本

v1.1.0（2019-10-08）是 1.1 系列的开篇，集中交付了大量框架级能力，多数变更至今仍构成 Hyperf 日常开发的核心体验。

路由解析前置与中间件修复

#401 新增了 Hyperf\HttpServer\Router\Dispatched 对象，用于存储解析完成的路由信息，并在用户中间件执行之前完成解析，便于后续使用；同时修复了路由带参数时中间件失效的问题。从源码结构看，Dispatched 承载了路由匹配的结果，是中间件链路与控制器分发之间的关键数据载体。

异步队列注解化：@AsyncQueueMessage

#402 新增 @AsyncQueueMessage 注解：在方法上定义此注解，即表明该方法的实际执行逻辑会被投递到 Async-Queue 队列中消费。这正是 Hyperf 异步任务从「手动封装 Job 类」走向「注解声明式」的关键一步。

当前仓库中该注解定义于 src/async-queue/src/Annotation/AsyncQueueMessage.php，其参数包括：

• pool：使用的消息队列连接池，默认 default；
• delay：消息延迟投递秒数，默认 0；
• maxAttempts：消息消费失败时的最大重试次数，默认 0（不限制）。

注解声明为 #<a href="https://link.gitcode.com/i/f1a24ed2e6aadf815e6dc1eec2e737b7" target="_blank">Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]，可作用于类与方法；其实际投递逻辑位于 [src/async-queue/src/Aspect/AsyncQueueAspect.php，Aspect 会读取注解的 maxAttempts 并构造 AnnotationJob 投递，maxAttempts 参数在 src/async-queue/src/AnnotationJob.php 中传入。

模型事件机制与 WebSocket 跨进程推送

• #420 为数据库模型引入新的事件机制，与 PSR-15 事件调度器配合，可解耦地定义 Listener 监听模型事件。
• #418 允许向任意 fd 发送 WebSocket 消息，即使当前 Worker 进程不持有该 fd，框架会自动通过进程间通信实现投递。

表单验证器组件

#429 文档所讲解能力的基础。

依赖注入与 OpenTracing 适配

• #596 为 @Inject 注解新增 required 参数。@Inject(required=false) 在依赖不存在时不再抛出 Hyperf\Di\Exception\NotFoundException，而是以默认值 null 注入；required 默认值为 true，构造器注入场景下可通过将参数声明为 nullable 达到同样效果。
• #478 更好地适配 OpenTracing 协议并兼容 Jaeger 分布式调用链追踪系统。
• #555 新增全局函数 swoole_hook_flags()，用于获取 SWOOLE_HOOK_FLAGS 常量定义的 Runtime Hook 等级，可在 bin/hyperf.php 中通过 define('SWOOLE_HOOK_FLAGS', SWOOLE_HOOK_ALL) 方式定义。

异步队列消费能力增强

• #597 为 AsyncQueue 消费者引入 Concurrent 控制消费速率；
• #599 支持根据当前重试次数设置该消息的重试等待时长，可实现阶梯式重试等待；
• #620 为 AsyncQueue 消费者增加自动重启机制。

AMQP 消费者 nack 支持

#648 为 AMQP Consumer 增加 nack 返回类型：当消费逻辑返回 Hyperf\Amqp\Result::NACK 时，抽象消费者会以 basic_nack 方法响应消息。

破坏性变更（升级 1.0 → 1.1 必读）

v1.1.0 的变更集中在容器、配置结构与命名调整上：

1. 新的 config/container.php 文件（#463）简化了容器初始化并优化注解缓存机制，内容如下：

<?php

use Hyperf\Di\Container;
use Hyperf\Di\Definition\DefinitionSourceFactory;
use Hyperf\Context\ApplicationContext;

$container = new Container((new DefinitionSourceFactory(true))());

if (! $container instanceof \Psr\Container\ContainerInterface) {
    throw new RuntimeException('The dependency injection container is invalid.');
}
return ApplicationContext::setContainer($container);

2. ConfigProvider 结构变更（#614、#617）：config/dependencies.php 移至 config/autoload/dependencies.php 且去掉 dependencies 层；ConfigProvider 中的 scan 配置增加一层 annotations，与配置文件结构对齐：

// 之前
'scan' => [
    'paths' => [__DIR__],
    'collectors' => [],
],

// 现在
'annotations' => [
    'scan' => [
        'paths' => [__DIR__],
        'collectors' => [],
    ],
],

3. 命令重命名（#638）：db:model 更名为 gen:model，并增加 Visitor 优化生成的 $connection 成员属性——当生成的模型类 $connection 属性值与父类一致时，不再生成该属性。

4. 移除项：#402 移除已弃用的 AsyncQueue::delay 方法；#563 移除 ServerInterface::SERVER_TCP 常量，改用 SERVER_BASE；#602 移除 Concurrent 的 timeout 参数。

二、v1.1.1 ~ v1.1.5：验证器、NSQ、计划任务与 RPC 补强

v1.1.1 - 2019-10-08（验证器与模型生成修正）

• #664 调整 gen:request 生成的 FormRequest 中 authorize 方法的默认返回值；
• #665 修复启动时永远自动生成代理类的问题；
• #667、#672 修复 ValidationMiddleware 在访问不存在路由、Action 参数为非对象类型时抛出未捕获异常的问题；
• #674 修复 gen:model 从数据库生成模型时表名错误的问题。

v1.1.2 - 2019-10-17（AMQP 速率限制）

• #722 为 AMQP Consumer 新增 concurrent.limit 配置，对协程消费进行速率限制；
• #678 为 gen:model 增加 ignore-tables 参数，并默认屏蔽 migrations 表（不生成对应模型）。

v1.1.3 - 2019-10-24（模型注释与 AMQP 事件）

• #745 为 gen:model 增加 with-comments 选项，控制是否生成字段注释；
• #747 为 AMQP 消费者增加 AfterConsume、BeforeConsume、FailToConsume 三个事件；
• #762 为 Parallel 特性增加协程控制功能；
• #767 将 AbstractProcess 的 running 属性更名为 listening（破坏性变更）。

v1.1.4 - 2019-10-31（测试客户端与服务监控）

• #778 Hyperf\Testing\Client 新增 PUT 和 DELETE 方法；
• #784 新增服务监控组件（metric）；
• #795 AbstractProcess 增加 restartInterval 参数，允许子进程异常或正常退出后延迟重启；
• #804 Command 增加 BeforeHandle、AfterHandle、FailToHandle 事件；
• #811 命令 di:init-proxy 不再主动清理代理缓存，如需清理请使用 vendor/bin/init-proxy.sh（行为变更）。

v1.1.5 - 2019-11-07（NSQ 与 Redis 集群）

• #812 计划任务支持集群下仅执行一次；
• #820 新增 hyperf/nats 组件；
• #832 新增 Hyperf\Utils\Codec\Json；
• #833 新增 Hyperf\Utils\Backoff（指数退避工具）；
• #852 为 Hyperf\Utils\Parallel 新增 clear() 方法清理所有已添加回调；
• #854 新增 Hyperf\GraphQL\GraphQLMiddleware 用于解析 GraphQL 请求；
• #859 支持 Consul 集群，可从 Consul 集群拉取服务提供者节点信息；
• #873 新增 Redis 集群客户端支持；
• #840 使用 \Swoole\Timer::* 替代 swoole_timer_* 函数。

三、v1.1.6 ~ v1.1.9：DB 组件、Session 与 DI 懒加载

v1.1.6 - 2019-11-14（轻量 DB 与 Session）

• #827 目录对应组件）；
• #905、#933 视图组件新增 twig、plates 模板引擎；
• #911 定时任务支持多实例下仅执行单实例；
• #913 增加监听器 Hyperf\ExceptionHandler\Listener\ErrorExceptionHandler；
• #921 新增 Session 组件；
• #931 Apollo 配置中心增加 strict_mode，自动将配置转换为对应数据类型；
• #937 Nats 组件新增消费者消费和订阅事件；
• #941 新增 Zookeeper 配置中心；
• #934 修改 WaitGroup 继承 \Swoole\Coroutine\WaitGroup；
• #928 模型缓存 Cacheable::query 批量修改数据时可删除对应缓存；
• #936 优化模型缓存 increment 在并发情况下可能产生的数据错误。

v1.1.7 - 2019-11-21（Retry 组件与注册机制调整）

• #860 新增 hyperf/retry 组件；
• #952 新增 ThinkTemplate 视图引擎支持；
• #973 JSON RPC 在 TCP 协议下新增连接池支持，通过 Hyperf\JsonRpc\JsonRpcPoolTransporter 使用连接池版本；
• #976 为 hyperf/amqp 新增 close_on_destruct 选项，控制代码执行析构函数时是否主动关闭连接；
• #944 重要变更：将组件内所有通过 @Listener、@Process 注解注册的方式改为通过 ConfigProvider 注册；
• #977 调整 init-proxy.sh 行为，改为只删除 runtime/container 目录；
• #968 修复 classes 与 annotations 两种 Aspect 切入模式同时存在于一个类时其中一个可能失效的问题。

v1.1.8 - 2019-11-28（Redis Lua 与 metric CUSTOM_MODE）

• #965 新增 Redis Lua 模块，用于管理 Lua 脚本；
• #1023 metric 组件 Prometheus 驱动新增 CUSTOM_MODE 模式；
• #1021 WebSocket 客户端新增默认端口支持，根据协议默认 80 和 443；
• #1034 去掉 AMQP Builder 的 arguments 参数 array 类型限制，允许 AmqpTable 等其他类型；
• #1039 在 CoreMiddleware 中自动将最新 ServerRequest 对象设置到 Context。

v1.1.9 - 2019-12-05（DI 懒加载与 PHP 7.4）

• #948 为 DI Container 增加懒加载功能；
• #1044 为 AMQP Consumer 增加 basic_qos 配置；
• #1056、#1081 DI Container 增加 define() 和 set() 方法，同时新增 Hyperf\Contract\ContainerInterface；
• #1059 job.stub 模板增加构造函数；
• #1084 支持 PHP 7.4，TravisCI 增加 PHP 7.4 运行支持。

四、v1.1.10 ~ v1.1.14：JSON-RPC、AMQP Keepalive 与新增组件

v1.1.10 - 2019-12-12

• #1108 重命名 TraceMiddeware 为 TraceMiddleware（拼写修正，破坏性变更）；
• #1111 将 ServiceRegisterListener 类成员属性和方法等级提升为 protected，便于重写；
• 修复 Guzzle 重试中间件状态码识别范围（2xx）、Retry 组件重试前未还原管道堆栈、数据库 sticky 模式连接回归连接池未重置状态、TCP 协议 JSONRPC Server 解析 JSON 失败无法返回预期 Error Response、Session 中间件保存 URL 时斜杠结尾被忽略等问题。

v1.1.11 - 2019-12-19

• #849 为 tracer 组件增加 span tag 配置功能；
• 修复 Register::resolveConnection 返回 null、配置文件形式下服务限流失效、CoroutineMemoryDriver::delKey 返回值错误、验证器 alpha_num 规则等问题。

v1.1.12 - 2019-12-26（新协议 jsonrpc-tcp-length-check）

• #1177 为 jsonrpc 组件新增 jsonrpc-tcp-length-check 协议，并优化部分代码；
• 修复 Collection::random 不支持 null、chunkById 不支持数组元素、operatorForWhere 的 operator 只能传 string 等 BUG；
• #1186 日志配置只填写 formatter.class 时，可使用默认 formatter.constructor 配置。

v1.1.13 - 2020-01-03（constants 国际化）

• #1137 constants 组件增加国际化支持；
• #1165 RequestInterface 新增 route 方法；
• #1195 Cacheable、CachePut 注解增加最大超时时间偏移量配置；
• #1204 database 组件新增 insertOrIgnore 方法；
• #1216 RenderInterface::render() 的 $data 参数添加默认值；
• #1217 将 zendframework/zend-mime 替换为 laminas/laminas-mine。

v1.1.14 - 2020-01-10（AMQP KeepaliveIO 与 super-globals）

• #1166 为 AMQP 增加 KeepaliveIO 功能；
• #1208 为 JSON-RPC 响应增加 error.data.code 传递 Exception Code；为 TransporterInterface 增加 recv 方法；修复 JSON-RPC TCP Server 下 Exception/error 无法正确处理、未检查 Request ID 与 Response ID 是否一致的问题；
• #1215 新增 hyperf/super-globals 组件，适配不支持 PSR-7 的第三方包；
• #1219 为 AMQP 消费者增加 enable 属性，控制消费者是否跟随 Server 一同启动；
• #1224 允许 Aliyun ACM 配置获取进程解析 UTF-8 字符，Worker 启动后自动获取一次配置，拉取的配置传递到自定义进程；
• #1235 AMQP 生产者执行 declare 后释放对应连接。

五、v1.1.15 ~ v1.1.19：命令工具链与配置中心完善

• v1.1.15（2020-01-10）：修复 AMQP 心跳失败导致子进程 Socket 通信不可用、JSONRPC 同一协程内连接混淆复用的问题。
• v1.1.16（2020-01-16）：async-queue 组件增加 QueueLength 事件；Consul 客户端增加 ACL token 支持；metric 组件增加 NoOp 驱动用于临时关闭功能；修复 keepaliveIO 下 socket 被消耗光、自定义进程存在 Timer 时无法重启、JSONRPC Request ID 为 null 时检查失败等问题；优化 gRPC 客户端断线自动重连、GC 时自动关闭连接、channel pool 非空、构造器与容器注入可用性等问题。
• v1.1.17（2020-01-24）：Apollo 组件增加 BootProcessListener 实现启动时拉取配置；crontab 组件增加 Command 模式支持；新增 hyperf/nsq 组件（NSQ 是实时分布式消息平台）；修复服务注册在同名不同协议下被覆盖、ConsumerProcess 缺失 $config 变量等问题。
• v1.1.18（2020-02-27）：metric 组件新增预制 Grafana 面板；新增 ModelRewriteInheritanceVisitor 重写 gen:model 生成的模型类继承；LoadBalancerInterface 新增 getNodes()；command 新增 AfterExecute 事件；logger 组件新增 processors 配置；HTTP Server 自动处理 HEAD 请求且不返回 Response body。
• v1.1.19（2020-03-05）：新增 describe:routes 命令显示路由细节；config-aliyun-acm 组件新增 ECS RAM authorization；PoolFactory 增加 getPoolNames()；Hyperf\DB\DB 新增 connection() 方法指定连接；gen:model 新增 property-case 选项设置成员属性命名风格。

gen:model 命令的选项体系在这一时期逐步成型。当前仓库中 src/database/src/Commands/ModelCommand.php 定义了完整选项，对应关系如下：

选项	简写	类型	说明
refresh-fillable	-R	VALUE_NONE	是否生成模型的 fillable 属性
table-mapping	-M	VALUE_OPTIONAL | VALUE_IS_ARRAY	表名映射，用于将表映射到指定类名
ignore-tables	无	VALUE_OPTIONAL | VALUE_IS_ARRAY	忽略指定表，不生成模型
with-comments	无	VALUE_NONE	是否生成字段注释
property-case	无	VALUE_OPTIONAL	属性命名风格，0：snake_case，1：camelCase

六、v1.1.20 ~ v1.1.25：事务注解、模型缓存与命令事件

v1.1.20 - 2020-03-12（@Transactional 注解）

• #1402，并有对应测试 src/db-connection/tests/TransactionalTest.php 验证其行为；
• #1412 增加 Hyperf\View\RenderInterface::getContents() 直接获取 View Render 渲染内容；
• #1416 增加 Swoole 事件常量 ON_WORKER_ERROR；
• #1405 修复模型存在 hidden 属性时模型缓存缓存字段数据不正确的问题。

v1.1.21 - 2020-03-19

• #1393 为 SwooleStream 实现更多方法；
• #1419 允许 ConfigFetcher 通过一个协程启动而无需额外启动一个进程；
• #1424 允许通过配置文件修改 session_name 配置；
• #1435 模型缓存增加 use_default_value 属性，自动修正缓存数据与数据库数据的差异；
• #1436 NSQ 消费者增加 isEnable() 方法控制消费者进程自启。

v1.1.22 - 2020-03-26（Filesystem 组件）

• #1440 NSQ 每个连接新增 enable 配置项控制该连接下所有消费者自启；
• #1451）；
• #1459 模型 Collection 新增 macroable 支持；
• #1463 Guzzle Handler 增加 on_stats 选项支持；
• #1452 变更建议：注入 Redis 客户端时推荐使用 \Hyperf\Redis\Redis 替代 \Redis（原因见 #938）；
• #1449 修复高基数请求路径的内存溢出问题。

v1.1.23 - 2020-04-02

• #1467 为 filesystem 组件新增默认配置；
• #1469 为 HandlerStackFactory 新增 getHandler() 方法，并尽可能使用 make() 创建 handler；
• #1480 RPC client 自动代理父接口的方法定义；
• #1481 异步队列创建消息时使用 make 方法创建；
• 修复 NSQ 数据量超过 max-output-buffer-size 接收失败、消费者中发布消息导致无法消费、requeue 消息时消费者意外重启等 BUG。

v1.1.24 - 2020-04-09

• #1501 新增 Symfony 命令行事件触发器，可与 hyperf/event 组件结合使用；
• #1502 为 @AsyncQueueMessage 注解新增 maxAttempts 参数，控制消息失败时重复消费次数（该参数当前保留在 src/async-queue/src/Annotation/AsyncQueueMessage.php 中，默认 0 表示不限制）；
• #1510 新增 CoordinatorManager，提供更优雅的启动/停止服务：启动前不响应请求，停止前保证循环逻辑正常结束；
• #1517 DI 容器懒加载支持接口继承和抽象方法继承；
• #1529 处理 response cookies 的 SameSite 属性；
• 修复单独使用 Redis 组件时 @mixin 注释被当成注解、引入 translation 后 constants 动态参数不生效、RPC 代理客户端无法处理 nullable 返回值、consul 组件 catalog 注册方法调用失败等问题。

v1.1.25 - 2020-04-09

• #1532 修复 --no-dev 条件下安装找不到 EventDispatcherInterface 接口的问题。

七、v1.1.26 ~ v1.1.32：快照与巅峰（含模型自定义类型转换）

v1.1.26 - 2020-04-16

• #1578 UploadedFile 支持 getStream 方法；
• #1563 修复服务关停后定时器 onOneServer 配置不重置；
• #1565 DB 组件重连 MySQL 时重置事务等级为 0；
• #1572 修复 gRPC Server CoreMiddleware 自定义类父类找不到报错；
• #1560 变更：cache 组件文件缓存引擎原生文件操作改为 Filesystem；
• #1568 变更：async-queue 组件 Redis 引擎中 \Redis 改为 RedisProxy。

v1.1.27 - 2020-04-23

• #1575 gen:model 生成的模型自动添加 relation、scope、attributes 变量注释；
• #1586 为 symfony/event-dispatcher 小于 4.3 时增加 conflict 配置，解决 SymfonyDispatcher 实现冲突 BUG；
• #1597 中 maxConsumption 默认值为 0，消费逻辑位于 src/amqp/src/Consumer.php，当 maxConsumption > 0 且累计消费次数达到该值时停止消费；
• #1603 为 WebSocket 服务新增基于 fd 存储的 Context；
• #1589 修复协程下文件锁可能造成死锁的问题；
• #1607 修复重写后的 go 方法返回值与 Swoole 原生方法不符。

v1.1.28 - 2020-04-30

• #1645 匿名函数路由支持参数注入；
• #1647，并配有 src/model-cache/tests/Handler/RedisStringHandlerTest.php 测试；
• #1654 新增 RenderException 统一捕获 view 组件抛出的异常；
• #1639 修复 rpc-client 从 consul 获取到不健康节点、结果为空时抛出 RequestException 等问题；
• #1650、#1624 修复 describe:routes 列表展示有误、路由 Handler 为匿名函数时执行失败等问题；
• #1655 修复 MysqlProcessor::processColumns 在 MySQL Server 8.0 无法正常工作。

v1.1.29（版本记录跳转说明）

按仓库记录，v1.1.29 未单独列出条目（changelog 中 v1.1.28 之后直接进入 v1.1.30），1.1 系列版本节奏以实际发布为准。

v1.1.30 - 2020-05-07

• #1616 新增 ORM 方法 morphWith 和 whereHasMorph（多态关联预加载与查询）；
• #1651 新增 socket.io-server 组件；
• #1666、#1669 新增 AMQP RPC 客户端；
• #1682 修复 RpcPoolTransporter 连接池配置不生效；
• #1683 修复 RpcConnection 连接失败后同一协程内无法重置连接。

v1.1.31 - 2020-05-14

• #1723 异常处理器集成 filp/whoops；
• #1730 为 gen:model 的 --refresh-fillable 选项新增简写 -R；
• #1696 修复 Context::copy 传入 keys 后无法使用；
• #1708、#1718 修复 socketio-server 内存溢出等 BUG；
• #1710 MAC 系统下不再使用 cli_set_process_title 设置进程名。

v1.1.32 - 2020-05-21（1.1 系列收官：模型自定义类型转换）

1.1 系列的最后一个版本，重点交付了 ORM 层多态查询补全与自定义类型转换能力：

• #1724 新增模型方法 Model::orWhereHasMorph、Model::whereDoesntHaveMorph、Model::orWhereDoesntHaveMorph，补全多态关联查询的否定与 or 组合能力；
• #1741 新增 Hyperf\Command\Command::choiceMultiple(): array 方法——因为 choice() 返回类型为 string，即使设置了 $multiple 参数也无法处理多选结果，新方法解决了命令行多选交互问题；
• #1742 新增模型自定义类型转换器功能：
  • 新增 interface Castable、CastsAttributes、CastsInboundAttributes；
  • 新增方法 Model\Builder::withCasts；
  • 新增方法 Model::loadMorph、Model::loadMorphCount、Model::syncAttributes。

这些接口与能力在当仓库均有完整实现：Castable、CastsAttributes、CastsInboundAttributes 位于 src/database/src/Model/Casts 目录（含 AsCollection、AsArrayObject 等内置转换类），withCasts 定义于 src/database/src/Model/Builder.php，loadMorph 等定义于 src/database/src/Model/Concerns/QueriesRelationships.php，属性同步逻辑集中在 src/database/src/Model/Concerns/HasAttributes.php，并有专门测试 src/database/tests/DatabaseModelCustomCastingTest.php 覆盖。此外 src/database/src/Model/CastsValue.php 提供了可同步回模型的抽象转换值基类，通过 syncAttributes() 在属性修改时通知模型。

• v1.1.32 修复项：模型多态查询关联为空时仍查询 SQL（#1734）；filesystem 组件 OSS HOOK 位运算错误导致 resource 判断不准确（#1739）；grafana.json 错误的 refId 字段值（#1743）；AMQP 组件使用其他连接池时 concurrent.limit 配置不生效（#1748）；连接池组件连接关闭失败时计数错误（#1750）；BASE Server 启动提示未考虑 UDP 服务（#1754）；时间为 null 时 datetime 验证器失败（#1764）；socketio-server 客户端初始化断开连接时报 Notice（#1769）。

八、1.1 系列演进规律与升级要点

版本节奏与主题分布

从 2019-10-08 到 2020-05-21，1.1 系列共发布 32 个版本，平均每 7 天一个版本，呈现「高频迭代、小步快跑」的节奏。演进主题大致分为三个阶段：

1. 框架能力奠基期（v1.1.0 ~ v1.1.5）：路由/中间件、注解异步队列、验证器、模型事件、服务监控、NSQ/NATS、Redis 集群；
2. 组件生态扩张期（v1.1.6 ~ v1.1.14）：轻量 DB、Session、Retry、super-globals、gRPC 客户端优化、AMQP KeepaliveIO、jsonrpc-tcp-length-check 协议；
3. 稳定与精细化期（v1.1.15 ~ v1.1.32）：命令工具链完善（describe:routes、gen:model 选项丰富）、配置中心完善、Filesystem、事务注解、模型自定义类型转换。

值得关注的破坏性变更清单

版本	变更内容	影响
v1.1.0	ConfigProvider 的 scan 增加 annotations 层；config/dependencies.php 移至 config/autoload/dependencies.php 且去掉 dependencies 层	组件与项目配置结构调整
v1.1.0	db:model 更名为 gen:model	命令名变更
v1.1.0	移除 SERVER_TCP、AsyncQueue::delay、Concurrent::timeout	删除 API
v1.1.3	AbstractProcess::running 更名为 listening	属性更名
v1.1.7	@Listener/@Process 注解注册改为 ConfigProvider 注册	组件注册机制变更
v1.1.10	TraceMiddeware 更名为 TraceMiddleware	类名拼写修正
v1.1.22	推荐 \Hyperf\Redis\Redis 替代 \Redis 注入	最佳实践变更

升级与查阅建议

• 若从 1.0 升级到 1.1，优先核对上表破坏性变更，尤其是容器配置结构与命令名变化；
• 若使用异步队列，@AsyncQueueMessage 的 maxAttempts（v1.1.24 引入）与消费者 Concurrent 速率控制（v1.1.0 引入）配合使用可构建健壮的消费链路；
• 若使用 AMQP，注意 concurrent.limit（v1.1.2）、basic_qos（v1.1.9）、maxConsumption（v1.1.27）、enable（v1.1.14）等消费端参数的组合语义；
• 模型层的多态查询与自定义类型转换能力集中在 v1.1.30 ~ v1.1.32 引入，相关实现可在 src/database/src/Model 目录中对照源码深入研读；
• 本文对应原文记录位于 docs/zh-tw/changelog/1.1.md，同系列其他版本可参考 docs/zh-tw/changelog/2.0.md、docs/zh-tw/changelog/3.0.md 等，英文版见 docs/en/changelog/1.1.md。

结语

Hyperf 1.1 系列的 32 个版本，完成了从框架基础能力到组件生态、再到精细化打磨的完整闭环。它确立了注解驱动异步队列、ConfigProvider 组件注册、轻量 DB、模型自定义类型转换等至今仍在演进的设计基因；同时，通过高频修复连接池、RPC、协程安全等底层问题，为 2.x 的稳定性打下了坚实基础。理解 1.1 的演进脉络，有助于开发者在使用新版 Hyperf 时，准确判断某项能力从哪个版本开始可用、哪些变更属于破坏性调整，从而在升级与选型中做出更稳妥的决策。