你是否正在构建一个SaaS平台，为不同的客户提供服务，但又希望所有客户的数据都存储在同一个数据库中，以降低运维成本和复杂性？这种单数据库多租户的架构模式虽然高效，却也带来了巨大的挑战：如何确保不同租户之间的数据严格隔离，避免用户看到或修改不属于自己的信息？手动在每一个数据库查询中添加 WHERE tenant_id = current_tenant_id 这样的条件，不仅工作量巨大，容易遗漏导致数据安全隐患，而且会使代码变得臃肿不堪，难以维护。
幸运的是，php社区的composer生态为我们提供了强大的解决方案。今天，我将向你介绍一个能够彻底解决这个痛点的Composer包：nunomazer/laravel-samehouse。它能让你在Laravel应用中实现优雅、自动化的单数据库多租户数据隔离。
Composer在线学习地址：学习地址
为什么选择 nunomazer/laravel-samehouse？
nunomazer/laravel-samehouse 是一个基于 HipsterJazzbo/Landlord 和 Torzer/awesome-landlord 改进而来的Laravel/Lumen包，专注于实现单数据库多租户。它的核心理念是：通过自动化的全局作用域（Global Scopes），确保所有针对租户模型的查询都只返回当前租户的数据。这意味着你无需在每个Eloquent查询中手动添加租户ID，大大简化了开发工作。
安装与配置：让魔法开始
首先，使用Composer将 nunomazer/laravel-samehouse 添加到你的项目中：
<code class="bash">composer require nunomazer/laravel-samehouse</code>
对于 Laravel 项目：
在 config/app.php 中注册 ServiceProvider：
<pre class="brush:php;toolbar:false;"> 'providers' => [ // ... NunoMazerSamehouseLandlordServiceProvider::class, ],
如果你喜欢使用 Facade，也可以注册：
<pre class="brush:php;toolbar:false;"> 'aliases' => [ // ... 'Landlord' => NunoMazerSamehouseFacadesLandlord::class, ],
为了更好地控制，你可以发布其配置文件：
<code class="bash">php artisan vendor:publish --provider="NunoMazerSamehouseLandlordServiceProvider"</code>
发布后，你可以在 config/landlord.php 中设置 default_tenant_columns，这对于那些没有明确指定 $tenantColumns 属性的模型非常有用。
对于 Lumen 项目：
在 bootstrap/app.php 中注册 ServiceProvider，并确保启用了Eloquent：
<pre class="brush:php;toolbar:false;">$app->register(NunoMazerSamehouseLandlordServiceProvider::class); $app->withEloquent(); // 确保这一行没有被注释掉
核心用法：定义租户上下文
nunomazer/laravel-samehouse 的一个关键点是：它无状态。这意味着你需要在每个请求中明确告知它当前是哪个租户在操作。最常见和推荐的做法是使用中间件（Middleware）。
假设你的用户表（users）中有一个 company_id 字段，用于关联用户所属的公司（租户）。你可以创建一个 SetTenant 中间件：
<code class="bash">php artisan make:middleware SetTenant</code>
然后，编辑 app/http/Middleware/SetTenant.php 文件：
<pre class="brush:php;toolbar:false;"><?php namespace AppHttpMiddleware; use Closure; use NunoMazerSamehouseFacadesLandlord; // 引入 Landlord Facade class SetTenant { /** * Handle an incoming request. * * @param IlluminateHttpRequest $request * @param Closure $next * @return mixed */ public function handle($request, Closure $next) { // 确保用户已登录，并且其 company_id 存在 if (auth()->check() && auth()->user()->company_id) { // 将当前请求的租户设置为认证用户的 company_id Landlord::addTenant('company_id', auth()->user()->company_id); } return $next($request); } }
最后，将这个中间件添加到 app/Http/Kernel.php 中的 web 或 api 中间件组，或者添加到特定的路由中：
<pre class="brush:php;toolbar:false;">// app/Http/Kernel.php protected $middlewareGroups = [ 'web' => [ // ... AppHttpMiddlewareSetTenant::class, // 添加到这里 ], 'api' => [ // ... AppHttpMiddlewareSetTenant::class, // 或者添加到这里 ], ];
通过这种方式，在每个请求开始时，Landlord 就会知道当前操作的租户ID，并将其应用到后续的所有数据库查询中。
你也可以通过 Landlord::removeTenant('company_id') 来移除当前租户上下文，或者使用 Landlord::hasTenant('company_id') 检查某个租户是否已被设置。
模型关联：自动数据隔离的魔法
要让你的Eloquent模型支持租户隔离，只需简单地使用 BelongsToTenants Trait：
<pre class="brush:php;toolbar:false;"><?php namespace AppModels; use IlluminateDatabaseEloquentModel; use NunoMazerSamehouseBelongsToTenants; // 引入 Trait class Product extends Model { use BelongsToTenants; // 使用这个 Trait // ... 其他模型属性和方法 }
现在，当你在 Product 模型上执行任何查询时，nunomazer/laravel-samehouse 都会自动添加 WHERE company_id = [当前租户ID] 条件：
<pre class="brush:php;toolbar:false;">// 假设当前租户的 company_id 是 1 $products = Product::all(); // 相当于 SELECT * FROM products WHERE company_id = 1 $product = Product::find(5); // 相当于 SELECT * FROM products WHERE id = 5 AND company_id = 1
如果 find(5) 对应的产品不属于当前租户，它将抛出 ModelNotFoundForTenantException 异常，而不是 Laravel 默认的 ModelNotFoundException，这有助于你更快地定位问题。
创建新模型时自动填充租户ID：
当你创建新模型实例时，如果 company_id 尚未设置，Landlord 会自动填充：
<pre class="brush:php;toolbar:false;">// 如果当前租户的 company_id 是 1，则会自动设置 product 的 company_id 为 1 $product = Product::create(['name' => '新产品', 'price' => 99.99]);
指定租户列：
如果你的模型使用的租户列名不是 default_tenant_columns 中定义的，或者你需要为特定模型指定不同的租户列，可以在模型中设置 $tenantColumns 属性：
<pre class="brush:php;toolbar:false;">class Order extends Model { use BelongsToTenants; public $tenantColumns = ['client_id']; // 为 Order 模型指定租户列为 client_id // ... }
进阶用法：打破隔离与临时禁用
有时，你可能需要查看所有租户的数据（例如在管理后台），或者在执行某些特定任务时暂时禁用租户隔离。
查看所有租户数据：
使用 allTenants() 方法可以临时禁用租户作用域：
<pre class="brush:php;toolbar:false;">// 这将返回所有公司的产品，忽略当前租户设置 $allProducts = Product::allTenants()->get();
禁用特定租户作用域：
如果你同时设置了多个租户（例如 company_id 和 branch_id），但只想禁用其中一个，可以使用 withoutGlobalScope()：
<pre class="brush:php;toolbar:false;">// 忽略 company_id 作用域，但其他租户作用域（如果有）依然生效 $products = Product::withoutGlobalScope('company_id')->get();
全局禁用/启用租户管理：
对于一些管理任务，你可能需要完全禁用 Landlord 的租户管理功能，然后再重新启用：
<pre class="brush:php;toolbar:false;">if (Landlord::isEnabled()) { Landlord::disable(); // 禁用租户管理 // 执行一些需要访问所有租户数据的管理任务 Landlord::enable(); // 重新启用租户管理 }
总结与优势
nunomazer/laravel-samehouse 为 Laravel 单数据库多租户应用提供了一个优雅且高效的解决方案。它的优势显而易见：
- 简化开发： 告别在每个查询中手动添加
WHERE子句的繁琐，让你的业务逻辑更聚焦。 - 提升安全性： 自动化的数据隔离机制，大大降低了因开发失误导致数据泄露的风险。
- 易于维护： 代码更整洁，逻辑更清晰，新功能开发和现有功能维护都变得更加容易。
- 灵活配置： 支持自定义租户列、临时禁用隔离等多种场景，满足不同业务需求。
- 单数据库优势： 让你在享受单数据库带来的部署和管理便利的同时，也能确保数据的严格隔离。
如果你正在为Laravel应用的多租户数据隔离问题而烦恼，nunomazer/laravel-samehouse 绝对值得一试。它将帮助你构建出更健壮、更易维护的SaaS应用。