Laravel 多租户 SaaS 架构设计思路 干货

tenant_id字段必须加索引，否则中等规模数据下查询会显著变慢甚至拖垮系统；全局作用域需手动验证生效；EnsureTenantAccess中间件须置于路由最外层；测试必须覆盖跨租户数据隔离。

tenant_id 字段必须加索引，否则查询会拖垮整个系统

没加索引的 tenant_id 在中等规模数据下（比如单表 50 万行），WHERE tenant_id = ? 查询就会明显变慢；高并发时可能触发数据库连接池耗尽。这不是理论风险，是线上真实踩过的坑——某次订单列表页加载从 200ms 涨到 3s，查出来就是 tenant_id 缺少索引。

实操建议：

• 所有含 tenant_id 的表，迁移里必须显式加索引：$table->index('tenant_id');
• 复合查询场景（如按租户+状态+时间查订单），优先建联合索引，把 tenant_id 放最左位：$table->index(['tenant_id', 'status', 'created_at']);
• 用 php artisan tinker 连进生产库执行 DB::select("SHOW INDEX FROM orders WHERE Key_name LIKE 'tenant_id%'"); 确认索引真实存在

全局作用域不能只靠 Trait 自动注册，必须手动验证是否生效

很多团队写了 BelongsToTenant Trait 并在 boot() 里调用 static::addGlobalScope()，但没验证它是否真被触发。结果上线后出现跨租户数据泄露——不是代码没写，而是模型没被自动加载，作用域根本没挂上。

验证方法很简单：

• 在模型里加个日志：static::addGlobalScope('tenant', function (Builder $builder) { Log::debug('tenant scope applied'); $builder->where('tenant_id', TenantContext::id()); });
• 用 Tinker 执行 AppModelsOrder::all();，看日志是否输出那行 debug
• 更直接：用 toSql() 看生成 SQL 是否含 WHERE tenant_id = ?，例如 AppModelsOrder::query()->toSql()

中间件 EnsureTenantAccess 必须放在路由组最外层，且不能被其他中间件绕过

EnsureTenantAccess 如果放在某个子中间件之后，或者被 auth:sanctum 之类的认证中间件“提前拦截”，就可能导致 TenantContext::set() 根本没执行，后续所有全局作用域都失效——因为 TenantContext::id() 返回 null，WHERE tenant_id = NULL 就等于没过滤。

典型错误配置：

• 在控制器方法里手动调用 TenantContext::set() —— 请求生命周期已过半，作用域注册早完成了
• 把中间件加在 api 或 web 组内部，而不是整个路由文件最顶层
• 用了 Laravel Octane 后没重载中间件顺序，导致中间件缓存未刷新

正确做法：在 routes/web.php 开头就写 Route::middleware(['web', 'ensure.tenant.access'])->group(...)，确保它是第一个被执行的业务中间件。

测试必须覆盖跨租户边界，不能只测单租户逻辑

只测“租户 A 能查自己数据”毫无意义。真正要卡住的是“租户 A 的请求，会不会意外拿到租户 B 的数据”。这需要构造明确的跨租户断言，而不是模拟登录再查列表。

最小可行测试结构：

• 创建两个租户：A（ID=1）、B（ID=2）
• 分别插入一条同名记录：Order::create(['tenant_id' => 1, 'order_no' => 'ORD-001']) 和 Order::create(['tenant_id' => 2, 'order_no' => 'ORD-001'])
• 用租户 A 的认证上下文发起 GET /api/orders，断言响应里只有 tenant_id === 1 的记录，且总数为 1
• 关键一步：去掉认证或伪造租户 ID，确认接口返回 403 或空结果，而非报错后泄露数据

没这四步，测试就是摆设。线上出问题从来不是“查不到”，而是“查多了”。