Hyperf分库分表路由绑定本质是运行时基于业务键(如user_id)动态计算连接名与表名,二者必须一致且可推导;连接名须与databases.php配置完全匹配、区分大小写;表名仅支持纯表名,不带库前缀;全量扫描需遍历所有分片组合并应用层聚合结果。

Hyperf 中分库分表的路由绑定,本质是“运行时根据业务键(如 user_id)动态决定用哪个数据库连接 + 哪张物理表”。它不依赖配置文件静态切换,而是靠代码逻辑实时计算,关键在于连接名(connection name)与表名(table name)的双重绑定必须一致且可推导。
路由必须基于业务键统一计算
所有读写操作都要用同一个业务字段(比如 user_id)去算库和表,否则数据错乱。例如:
- 插入订单时用 $userId % 8 算出表后缀,同时用 intdiv($userId % 8, 4) 算出 db0 或 db1;
- 查询该用户订单时,必须用完全相同的公式,否则可能查不到或查错库;
- 不能一部分逻辑用 user_id,另一部分用 order_no 或时间戳——除非你设计的是多维分片策略并已完整覆盖所有路径。
连接名必须在配置中真实存在且可被 Db::connection() 识别
Hyperf 的 Db 组件只认 config/autoload/databases.php 里定义的 connection name。路由函数返回的连接名(如 "db0"、"read_pool_1")必须与配置中的 key 完全一致:
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
- 配置里写的是 'db0',代码里就不能返回 'database0' 或 'DB0';
- 连接名区分大小写,且不能含空格或特殊字符;
- 如果用了读写分离,写操作只能走 write 连接,读操作才可走 read 连接,不能混用。
表名需与实际物理表严格匹配,且不能带库名前缀
Db::table('orders_3') 中的参数只是表名,不是“库.表”全名。Hyperf 不支持跨库 JOIN,也不允许在 table() 方法里传入 db0.orders_3 这类格式:
- 正确:Db::connection('db0')->table('orders_3')->insert(...);
- 错误:Db::connection('db0')->table('db0.orders_3')->insert(...);
- 表名必须是纯字符串,且对应目标库中真实存在的表;
- 建表脚本需提前在每个分库中执行,比如 db0 和 db1 都要有 orders_0 ~ orders_7 共 8 张表。
全量扫描需显式遍历所有分片组合
当无法用业务键定位(如后台导出全部订单),就得手动聚合所有分库分表的结果。这时不能只循环表名或只循环连接名,而要按路由策略生成完整的 [connection, table] 对:
- 调用 ShardingStrategy::getAllShards() 获取全部分片配置;
- 对每个 ['connection' => 'db0', 'table' => 'orders_0'] 单独查询,再合并结果;
- 注意分页、排序、去重等逻辑需在应用层做,数据库层无法统一处理。


















