Hyperf 多数据库连接通过配置驱动+显式注册+运行时解析实现,核心是 DbFactory 与 ConnectionResolverInterface 配合;配置在 databases.php 中,每个连接名对应独立 Connection 实例,注入 key 为 db.connection.{name},运行时通过 Db::connection('name') 或 #[Inject("db.connection.name")] 获取。

Hyperf 容器注入多数据库连接,不是靠“自动扫描”或“魔法绑定”实现的,而是通过配置驱动 + 显式注册 + 运行时解析完成的。底层核心是 DbFactory 和 ConnectionResolverInterface 的配合,容器只负责把配置转成连接实例并缓存,不参与 SQL 执行逻辑。
配置文件定义连接名与参数
在 config/autoload/databases.php 中,connections 数组里的每个键(如 default、log_db)就是连接名,也是后续注入/获取的唯一标识:
- 每个连接必须包含完整驱动信息:
driver、host、port、database、username、password -
pool子项需显式声明,包括min_connections、max_connections等,不能依赖默认值混用不同版本实例 - 若连接使用非标准认证(如 MySQL 8.0 的
caching_sha2_password),需在options中补全 PDO 层参数
DbFactory 根据连接名生成 Connection 实例
框架启动时,DbFactory 会遍历 connections 配置,为每个连接名创建一个独立的 Connection 实例,并注入到容器中,key 为 db.connection.{name}(例如 db.connection.log_db):
- 这个过程由
Hyperf\Database\ConnectionFactory完成,它封装了 PDO 构建、连接池初始化、异常重试等细节 - 每个
Connection实例持有自己专属的连接池对象(Pool),彼此隔离,互不影响 - 连接池内连接复用基于协程上下文,不会跨协程错乱
运行时通过 ConnectionResolver 切换上下文
Db::connection('log_db') 表面是静态调用,实际委托给 ConnectionResolver:
- 它从容器中取出
db.connection.log_db对应的实例,返回已初始化好的Connection - 该实例自带完整的查询构建器(QueryBuilder)、事务管理器(TransactionManager)、事件分发器(Dispatcher)
- Eloquent 模型中设置
protected $connection = 'report_db',本质也是触发同一套 resolver 逻辑
自定义注入需明确指定连接名
若要在服务类中直接注入某个特定库的连接,不能写 #[Inject] protected Db $db;(它只会注入 default),而要:
- 用容器 ID 注入:
#[Inject("db.connection.log_db")] protected Connection $logDb; - 或通过工厂手动获取:
$this->dbFactory->get('log_db'),前提是DbFactory已注入 - 注意:连接名大小写敏感,且不能含空格或特殊字符,否则容器无法匹配


















