Laravel模型查询范围详解

Laravel全局查询范围看似只是为模型自动添加查询条件的便捷工具，实则是一把双刃剑：它会在所有查询中静默生效，一旦注册不当（如未在boot()中正确声明）、排除失当（如闭包未命名导致无法关闭）或滥用上下文（如在作用域中调用Auth或DB查询），轻则引发数据遗漏、重复过滤，重则让后台管理、队列任务、Artisan命令甚至数据库迁移直接崩溃；真正考验开发者功力的，不是如何“加上”全局条件，而是如何在多作用域叠加、字段冲突、运行环境多变的复杂场景下，精准控制、安全绕过并保持数据一致性。

全局查询范围（Global Scopes）不是“加个条件就行”，而是会无声无息地改写所有查询——用错或漏排除，轻则数据查不全，重则后台管理、数据迁移直接出错。

全局作用域必须注册在 boot() 里，且不能晚于其他静态初始化

模型类加载时，boot() 是唯一保证被调用且只调用一次的地方。如果把 addGlobalScope() 写在构造函数、静态属性初始化、或某个辅助方法里，它可能根本不会执行，或者被多次注册（导致条件重复叠加）。

• 闭包方式：必须在 boot() 开头就注册，例如 static::addGlobalScope('active', function ($builder, $model) { ... });
• 类方式：同样在 boot() 中调用 addGlobalScope(new TenantScope)，不要延迟到第一次查询时才注册
• 若模型用了 SoftDeletes trait，它的全局作用域也是在 boot() 注册的——你的自定义作用域要明确考虑与它的执行顺序，避免 where 条件冲突（比如两个作用域都对 deleted_at 做判断）

withoutGlobalScope() 只能排除已注册的作用域，闭包作用域必须带键名

闭包注册时不传键名，Laravel 会生成一个随机字符串作为内部标识，你无法在 withoutGlobalScope() 中引用它。这意味着：一旦用了匿名闭包，就等于放弃了按需关闭的能力。

• 正确做法：注册时显式指定字符串键名，如 addGlobalScope('tenant', function (...) { ... })，之后可用 withoutGlobalScope('tenant')
• 类作用域可直接传类名，如 withoutGlobalScope(TenantScope::class)
• 想一次排除多个？传数组：withoutGlobalScope([TenantScope::class, 'tenant'])，但注意：键名和类名不能混用同一种排除方式

全局作用域里别做 DB 查询、别依赖请求上下文

全局作用域会在任何地方触发：队列任务、Tinker、Artisan 命令、甚至数据库迁移回滚时。此时 request() 不存在，auth() 可能未初始化，DB 连接也可能尚未就绪。

• 常见错误：在作用域里调用 Auth::id() 或 session('tenant_id') —— 在命令行运行 php artisan tinker 时必然报错
• 更安全的做法是把租户 ID 等上下文信息提前注入（如通过中间件写入静态属性），或改用本地作用域 + 显式传参
• 绝对不要在 apply() 方法里调用 DB::table(...)->get() 或其他查询，这会导致 N+1 和事务不一致

真正难处理的从来不是怎么加全局条件，而是怎么在特定场景下干净地绕过它——尤其是当多个全局作用域叠加、又共用同一个字段（比如 tenant_id 和 status）时，where 顺序、NULL 处理、索引覆盖都会立刻暴露出来。

终于介绍完啦！小伙伴们，这篇关于《Laravel模型查询范围详解》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！