Hyperf 3.0 协程中 Eloquent 的 with() 预加载可能失效,因协程连接复用、无共享一级缓存、懒加载未禁用及关系未显式声明;须禁用懒加载、限定字段查询、改用两段式或 JOIN 替代,并结合缓存与日志监控确保生效。

Hyperf 3.0 在协程环境下使用 Eloquent ORM 的 with() 预加载,能有效避免 N+1 查询,但需注意其底层行为与传统 PHP-FPM 环境存在关键差异——协程模型下连接复用、生命周期和缓存作用域都不同,单纯调用 with() 不一定自动生效,必须配合配置与写法优化。
预加载在 Hyperf 协程中为何可能失效
Hyperf 的 Eloquent 是基于 Swoole 协程 MySQL 客户端改造的,with() 默认仍走懒加载逻辑,若未显式触发预加载或模型关系未正确声明,协程内多次请求可能复用同一连接但无法共享查询上下文,导致看似“已 with”,实则仍逐条查关联表。
- 关系定义未启用
shouldLoad()或未设置$with属性,with()调用会被忽略 - 协程间无共享一级缓存(如 Laravel 的 Query Builder 缓存),每次请求都是独立上下文
- 未开启
Hyperf\Database\Model\Relations\Relation::disableEagerLoads()以外的拦截机制时,嵌套层级深的with('a.b.c')可能退化为多轮查询
确保 with 生效的 3 个硬性操作
不是加了 with() 就万事大吉,以下三点缺一不可:
-
模型关系必须显式声明加载方式:在关联方法中添加
->select(['id', 'user_id', 'title'])限定字段,并返回HasMany::class实例(非链式调用后丢弃) -
禁用懒加载代理:在模型顶部加
protected $lazyLoading = false;,防止访问$model->relation触发隐式查询 -
强制使用 selectinload 行为:Hyperf 未原生支持
selectinload,需手动改写为两段式查询——先查主表 ID 列表,再用whereIn('user_id', $ids)批量查关联表,最后在内存中合并(适合一对多场景)
结合协程连接池的预加载增强策略
Hyperf 的 DbPool 支持并发复用连接,但预加载本身不降低单次查询复杂度。真正提升在于减少往返次数与锁竞争:
- 对高频读取的关联数据(如用户角色、分类标签),在
with()基础上叠加cache():使用Hyperf\Cache\Annotation\Cacheable注解缓存预加载结果,TTL 设为业务可接受的分钟级 - 避免在协程内嵌套事务中用
with(),因事务上下文隔离会导致预加载 SQL 被拆分;应将预加载逻辑移至事务外,或改用DB::table()->join()原生 JOIN - 监控实际 SQL 数量:启用
Hyperf\Database\Logger\SlowQueryLogger,观察日志中是否出现重复SELECT * FROM orders WHERE user_id = ?—— 出现即代表预加载未命中
替代方案:JOIN 查询更可控
当 with() 在复杂条件(如带 where/in/limit 的关联筛选)下不稳定时,直接手写 JOIN 更可靠:
- 用
DB::table('users')->join('orders', 'users.id', '=', 'orders.user_id')...显式控制关联逻辑 - 配合
groupBy('users.id')和聚合函数(COUNT,MAX)避免笛卡尔积膨胀 - 对需要分页的列表,优先用
fromSub()子查询封装 JOIN 结果,再对外层分页,防止LIMIT错位











