Hyperf多租户数据库切换方法

本文深入解析了Hyperf框架下实现多租户数据库动态切换的核心机制与常见误区，强调租户标识必须在中间件的process()方法中从请求头、子域名或路径前缀安全提取，并通过协程上下文透传；真正的数据库切换关键在于连接首次创建时由自定义DbConnectionFactory读取上下文动态生成库名，而非事后调用purge或reconnect——后者因协程隔离和连接生命周期限制而无效；更需警惕的是，整个请求链路（DAO、Model、事务等）均不会自动感知租户上下文，必须通过统一封装的租户感知数据访问层（如TenantDB工具类）强制保障所有操作精准路由到对应租户库，否则极易引发跨租户数据污染。

Middleware里怎么拿到租户标识

租户标识通常来自请求头（如 X-Tenant-ID）、子域名（tenant1.example.com）或 URL 路径前缀（/t/tenant1/users）。中间件中不能直接依赖全局变量或静态属性，必须从 ServerRequestInterface $request 中提取：

• 请求头：用 $request->getHeaderLine('X-Tenant-ID')
• 子域名：先取 $request->getUri()->getHost()，再用 explode('.', ...) 拆分
• 路径前缀：用 Hyperf\Stringable\Str::before($request->getUri()->getPath(), '/', 2) 或正则匹配

注意：别在中间件构造函数里提前读取——那时请求上下文还没注入；所有解析逻辑必须放在 process() 方法内。

怎么在Middleware里动态切换DB连接

Hyperf 的 DB::connection('xxx') 是运行时绑定的，但「连接名」本身是静态配置项。真正要换的是底层连接池实例的引用。推荐做法是：不新建连接名，而是复用已配置的连接模板，用协程上下文覆盖当前请求的默认连接。

• 在 config/autoload/db.php 中预定义好多个租户连接模板（如 'tenant_template'），但不填 database 字段
• 中间件中用 Hyperf\Context\Context::set('db.tenant_id', $tenantId) 存租户 ID
• 配合自定义 DbConnectionFactory，在连接创建时读取上下文中的 tenant_id，拼出真实库名（如 "tenant_{$id}_core"）并写入连接配置

示例关键代码片段：

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
    $tenantId = $request->getHeaderLine('X-Tenant-ID');
    if (!$tenantId) {
        throw new BadRequestHttpException('Missing X-Tenant-ID');
    }
    Context::set('db.tenant_id', $tenantId);
    return $handler->handle($request);
}

这个动作本身不触发 DB 连接，只是为后续 DAO 层调用埋下上下文依据。

为什么不能直接调用 DB::purge() 或 DB::reconnect()

因为 DB::purge() 清空的是连接池工厂里的缓存实例，而 Hyperf 的连接池是协程隔离的——你在当前协程 purge 掉一个连接，不影响其他协程，但本协程后续第一次 DB::connection()->select(...) 仍会按原始配置重建连接，不会自动读取你刚 set 的上下文。

• DB::reconnect() 只对已存在的连接实例生效，且它不感知租户上下文
• 强行在中间件里执行 DB::connection()->reconnect() 很可能报错：连接尚未初始化，或被其他中间件提前使用过
• 真正的租户切换必须发生在连接「首次创建」那一刻，而不是创建后修补

所以必须把租户信息透传到连接工厂层，而非在中间件里操作已存在的连接对象。

租户数据库切换最容易被忽略的点

不是“怎么切”，而是“切完之后谁来保证整个请求链路都用对库”。比如：

• Service 层调用 DB::select() 时，默认走 default 连接，除非显式写 DB::connection('tenant_template')
• Model 类如果没重写 $connection 属性，也会忽略上下文，继续连 default
• 事务开启（DB::transaction()）时，若未指定连接名，会绑定到 default，导致跨租户混写

解决方式只有一个：所有数据访问入口必须统一走封装好的租户感知方法，例如提供一个 TenantDB 工具类，内部自动读取 Context::get('db.tenant_id') 并返回对应连接实例。别指望框架自动帮你完成这层映射。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Hyperf多租户数据库切换方法》文章吧，也可关注golang学习网公众号了解相关技术文章。