Hyperf中实现读写分离需手动配置多个独立连接池（如db.write、read_pool_1），并在查询时显式指定连接名，Model用on()、Db用connection()，事务仅限单池，无自动SQL类型分流机制。
Hyperf 中配置多个 Database 连接池实现读写分离
Hyperf 默认的 db 组件不自动区分读/写连接，必须手动定义多个连接池（如 db.write 和 db.read），再通过自定义逻辑或扩展组件路由 SQL。直接改 config/autoload/database.php 并不能让框架自动识别“哪些是读、哪些是写”——它只认你配的连接名。
- 每个连接池需独立配置 host、port、database、username 等，不可共用同一组参数
- 推荐为读库单独起名，例如
read_pool_1、read_pool_2，避免和default混淆 - 连接池名必须全小写、不含点号以外的特殊字符，否则
Db::connection('read.pool')会报Connection [read.pool] not found - 若使用 MySQL 主从复制，读库建议开启
strict_type => false和fetch_mode => PDO::FETCH_ASSOC，减少类型转换开销
在 Model 层手动指定读连接池
Hyperf 的 Model 类默认走 default 连接池，要走读库，得显式调用 on() 方法。这不是装饰器或注解能自动触发的，必须写在查询链路里。
-
User::on('read_pool_1')->where('status', 1)->get()是有效写法；User::on('read_pool_1')->save()则大概率失败（从库通常禁止写） - 不要在
boot()或构造函数里预设$connection属性来“全局切换”，Model 的静态方法（如find()、all()）不继承实例连接设置 - 关联查询（
with()）默认仍走主连接，需对关联模型也显式调用on()，例如：User::on('read_pool_1')->with(['posts' => fn ($q) => $q->on('read_pool_1')])
用 Db::select() / Db::table() 手动选连接池
原生查询比 Model 更灵活，但容易漏掉连接池切换。尤其 Db::table('users') 默认永远走 default，哪怕你在 Model 里已切过读库。
- 正确写法：
Db::connection('read_pool_1')->table('users')->where('id', 1)->first() -
Db::select()不接受连接名参数，必须先Db::connection('xxx')再链式调用 - 事务（
Db::transaction()）只能绑定单个连接池，跨读写池的事务无意义且会报错 —— MySQL 从库不支持BEGIN - 注意
Db::raw()中的 SQL 不会自动重写，如果写了INSERT却连到了读池，会直接抛出SQLSTATE[HY000]: General error: 1290 The MySQL server is running with the --read-only option
为什么不能靠中间件或 AOP 自动分流？
Hyperf 没有内置的“读写分离中间件”，社区常见方案（如监听 DbQueryExecuted 事件）仅适合日志或监控，无法在 SQL 执行前动态改连接池 —— 因为 Db 实例在构建时就绑定了连接，不是每次查询都重新解析 SQL 类型。
- SELECT/INSERT/UPDATE/DELETE 的判断必须发生在查询构造阶段，而非执行后
- 试图用 AOP 拦截
QueryBuilder::get()并替换连接，会破坏 QueryBuilder 内部状态，导致toSql()、dump()异常 - 真正可靠的分流逻辑，应封装进自定义 Repository 或 Service 方法中，例如：
UserRepository::findRead($id)内部固定走read_pool_1 - 如果项目已大量使用
Db::table()，建议统一抽象一层ReadDb和WriteDbFacade，避免散落各处的手动connection()
读写分离不是加几个配置就能生效的架构，关键在查询发起点是否明确连接归属。Hyperf 的连接池机制很干净，但也因此不会替你做语义判断 —— 它只管连，不管你是读是写。
