Hyperf框架中实现单表字段版多租户模型的最佳实践

多租户架构概述

多租户架构是现代SaaS应用中的常见设计模式，它允许单个应用实例服务多个客户（租户），同时保持数据隔离。在数据库层面，多租户主要有三种实现方式：

1. 独立数据库：每个租户拥有独立的数据库实例
2. 共享数据库独立Schema：同一数据库实例下不同Schema隔离数据
3. 共享数据库共享表：通过表中特定字段区分租户

本文重点介绍第三种方式，即通过单表字段标识租户的实现方案，这种方案在Hyperf框架中具有实现简单、维护成本低的优势。

Hyperf中的多租户实现方案

在Hyperf框架中，我们可以利用模型特性(Trait)和全局作用域(Global Scope)优雅地实现多租户数据隔离。核心思路是：

1. 为每个需要多租户隔离的模型表添加tenant_id字段
2. 通过全局作用域自动为所有查询添加租户过滤条件
3. 提供灵活的方法覆盖或扩展默认租户行为

核心代码实现

TenantTrait 实现

TenantTrait是核心功能载体，主要提供以下能力：

trait TenantTrait
{
    use HasGlobalScopes;

    // 自动注册全局作用域
    public static function bootTenantTrait(): void
    {
        static::addGlobalScope(new TenantScope());
    }

    // 提供链式tenant方法覆盖默认租户过滤
    public static function scopeTenant(Builder $builder, array|string $_tenantId): Builder
    {
        if (empty($_tenantId)) {
            return $builder;
        }
        return $builder->withoutGlobalScope(TenantScope::class)
            ->withGlobalScope(TenantScope::class, function (Builder $builder) use ($_tenantId) {
                $builder->whereIn($builder->getModel()->getQualifiedTenantIdColumn(), $_tenantId);
            });
    }

    // 获取租户字段全名（带表名前缀）
    public function getQualifiedTenantIdColumn(): string
    {
        return $this->qualifyColumn(empty($this->tenant) ? 'tenant_id' : $this->tenant);
    }
}

TenantScope 实现

TenantScope是具体的过滤逻辑实现：

class TenantScope implements Scope
{
    public function apply(Builder $builder, Model $model): Builder
    {
        return $builder->whereIn($model->getQualifiedTenantIdColumn(), ['当前租户ID']);
    }
}

使用方式

1. 基础用法：在模型基类中use TenantTrait，所有继承该基类的模型自动获得多租户能力

class BaseModel extends Model
{
    use TenantTrait;
}

2. 自定义租户字段名：在特定模型中覆盖默认tenant_id字段名

class User extends BaseModel
{
    protected $tenant = 'custom_tenant_id';
}

3. 临时覆盖租户过滤：查询时动态指定租户范围

// 查询特定租户数据
User::tenant([1, 2])->get();

// 查询所有租户数据（慎用）
User::withoutGlobalScope(TenantScope::class)->get();

方案优势分析

1. 无侵入性：通过Trait方式引入，不影响现有业务代码
2. 灵活性：支持自定义租户字段名和动态租户范围指定
3. 安全性：默认强制租户隔离，避免数据泄露风险
4. 性能友好：基于数据库原生WHERE条件过滤，效率高

最佳实践建议

1. 建议在中间件中设置当前租户上下文，确保全局一致
2. 对于租户ID获取逻辑，建议抽象为独立服务类
3. 关键业务操作建议显式指定tenant()范围，避免上下文丢失
4. 定期审计SQL日志，确保所有查询都正确添加了租户过滤条件

总结

Hyperf框架结合Trait和Global Scope提供的这套多租户实现方案，以极简的代码实现了强大的租户隔离能力，非常适合中小型SaaS应用的快速开发。开发者可以根据实际业务需求，灵活调整租户策略，在保证数据隔离的同时，不影响系统整体性能。