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 执行
App\Models\Order::all();，看日志是否输出那行 debug - 更直接：用
toSql()看生成 SQL 是否含WHERE tenant_id = ?，例如App\Models\Order::query()->toSql()
中间件 EnsureTenantAccess 必须放在路由组最外层，且不能被其他中间件绕过
EnsureTenantAccess 如果放在某个子中间件之后，或者被 auth:sanctum 之类的认证中间件“提前拦截”，就可能导致 TenantContext::set() 根本没执行，后续所有全局作用域都失效——因为 TenantContext::id() 返回 null，WHERE tenant_id = NULL 就等于没过滤。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
典型错误配置：
- 在控制器方法里手动调用
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 或空结果，而非报错后泄露数据
没这四步，测试就是摆设。线上出问题从来不是“查不到”，而是“查多了”。
