hyperf 中模型需显式绑定指定数据库连接以实现多租户等隔离场景,可通过模型类 $connection 属性、继承基类或工厂动态指定;注意跨库不支持 join、事务及自动关联,须分步查询与最终一致性处理。

Hyperf 中批量模型分别绑定数据库连接,核心是让每个模型明确归属某个连接名,而不是共用 default。这适用于多租户、分库分表、读写分离或业务逻辑隔离等场景。关键不在“批量操作”,而在于“批量定义模型与连接的映射关系”。
模型级静态绑定 connection 属性
最直接的方式是在每个 Eloquent 模型类中显式声明 $connection。这是 Laravel 兼容机制,Hyperf 完全支持:
- 在
app/Model/User.php中设置protected $connection = 'mysql_tenant_a'; - 在
app/Model/Order.php中设置protected $connection = 'mysql_tenant_b'; - 所有对该模型的查询、新增、更新、删除都会自动走对应连接,无需每次手动调用
Db::connection()
按命名空间统一配置连接(适合批量管理)
若模型数量多、分组清晰(如按租户、模块划分),可在模型基类中统一处理,避免重复写 $connection:
- 新建基类
app/Model/TenantAModel.php,设protected $connection = 'mysql_tenant_a'; - 让
User、Profile等租户 A 的模型继承该基类 - 同理建
TenantBModel绑定mysql_tenant_b - 后续新增模型只需选对基类,连接即自动生效
运行时动态绑定(配合工厂或上下文)
当连接名需根据请求参数(如 tenant_id、region)动态决定时,不建议硬编码在模型里,而应通过封装层控制:
- 定义一个模型工厂类,例如
TenantModelFactory - 传入 tenant_id 后,内部调用
ShardingStrategy::getConnection($tenantId)算出连接名 - 再用
new User(['connection' => $connName])或User::on($connName)构造实例 - 批量操作时可循环调用该工厂,确保每批数据都落在正确库上
注意跨连接的限制与规避
Hyperf 不支持跨连接 JOIN、事务跨库提交、Eloquent 关联自动跨库加载。所以:
- 关联模型必须使用相同
$connection,否则会查错库或报错 - 涉及多库数据聚合,应改用原生查询分步拉取,再在 PHP 层合并
- 事务只能作用于单个连接内,多库操作需用最终一致性方案(如本地消息表 + 补偿)











