LaravelEloquent全局作用域使用教程

Laravel Eloquent 全局作用域（Global Scopes）并非“魔法”，而是一种在查询构建阶段自动注入 WHERE 条件的可控机制——它确能强制约束 select/update/delete/softDelete 等 Eloquent 查询路径，但绝不适用于原生 DB 操作、关联预加载（with）默认场景，也不生效于被显式移除或未正确注册的情况；本文深入剖析其原理边界、多租户隔离（TenantScope）的健壮实现要点（强调上下文解耦与 CLI/队列兼容性）、静态与动态注册的本质差异，并直击开发者最常踩坑的三大失效原因：误用模型实例化方法、混淆查询构建与执行时机、以及表结构与字段名不匹配导致的静默失效，助你真正掌握这一强大却易被误解的核心能力。

什么是Eloquent Global Scopes，它真能“强制”加查询条件？

能，但不是魔法——Global Scopes 是 Laravel 在模型查询构建阶段自动注入 where 条件的机制，只要模型被用于 select、update、delete（含 softDelete），且未显式移除，就会生效。它的“强制性”依赖于你是否在所有查询路径中都用了该模型，以及是否误用 withoutGlobalScopes() 或 withoutGlobalScope()。

常见误判场景：关联预加载（with()）默认不触发 Global Scopes，除非你在关联定义里也应用了相同 scope，或手动在关系方法中调用 where...；另外，原生 DB 查询、DB::table() 完全绕过 Eloquent，自然也不受约束。

怎么写一个带租户隔离的全局作用域（TenantScope）？

典型业务需求：多租户系统中，每个请求需自动过滤出当前租户（tenant_id）的数据。关键点在于 scope 必须是可复用、可测试、不硬编码租户 ID 的类。

• 新建类 TenantScope 实现 Illuminate\Database\Eloquent\Scope 接口，重写 apply() 方法
• 租户 ID 从请求上下文获取（如 request()->attributes->get('tenant') 或通过服务容器解析的 TenantManager），**不能从 session 或全局变量直接读取**，否则 CLI 命令或队列任务会失效
• 在 apply() 中使用 $builder->where('tenant_id', $tenantId)，不要用 whereNotNull 或 whereExists 等复杂逻辑，除非你明确需要
• 务必实现 remove() 方法，用于测试或临时跳过（例如数据迁移时）

class TenantScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        $tenantId = app(TenantManager::class)->currentId();
        if ($tenantId) {
            $builder->where('tenant_id', $tenantId);
        }
    }

    public function remove(Builder $builder, Model $model)
    {
        $builder->whereNotNull('tenant_id'); // 占位，实际移除靠 Builder 内部机制
    }
}

怎么注册全局作用域？静态 vs. 动态方式有什么区别？

两种主流注册方式：模型类内静态绑定（推荐），或服务提供者中动态绑定。区别不在功能，而在生命周期和可维护性。

• 静态注册（在模型中）：重写 boot 方法，调用 static::addGlobalScope(new TenantScope)。优点是作用域与模型强绑定，IDE 可跳转，测试时容易 mock；缺点是无法根据环境（如测试/本地）动态开关
• 动态注册（在 AppServiceProvider::boot()）：用 Model::addGlobalScope() 绑定。适合需统一管理多个模型 scope 的场景，但容易造成“谁注册了什么”不清晰，调试困难
• 注意：addGlobalScope('name', new Scope) 的字符串名可用于后续 withoutGlobalScope('name') 精确移除；若只传实例，移除时必须传相同实例引用

为什么 sometimes 查询没走 Global Scopes？排查这三点

不是 scope 失效，而是你没在它起作用的路径上。

• 用了 new static 或 newInstance()：这些方法返回的是新模型实例，不触发查询，自然不走 scope；scope 只影响 query() 构建器行为
• 调用了 toSql() 或 explain()：这些是构建器方法，scope 已应用，但如果你在调用前用了 withoutGlobalScopes()，那 SQL 就真没条件
• 模型用了 protected $table = 'xxx' 但数据库表实际是视图或有别名：scope 中的 where('tenant_id', ...) 会按当前模型表名拼字段，如果视图里字段叫 org_id，就得在 scope 里写对字段名，否则条件无效且无报错

最稳妥的验证方式：开启查询日志（DB::enableQueryLog()），执行 Model::first() 后看 DB::getQueryLog() 输出的 SQL 是否含预期 WHERE tenant_id = ?。

到这里，我们也就讲完了《LaravelEloquent全局作用域使用教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！