Laravel如何做模型作用域_Laravel全局与局部查询范围【指南】

模型作用域这玩意儿，最怕的就是你以为“加个函数就能用”，结果发现全局作用域会偷偷摸摸改你所有查询，而局部作用域呢，不显式调用就等于没写。说到这儿，先聊几个容易翻车的点。

全局作用域必须注册到 boot 方法里才生效

是不是已经写好了一个全局作用域类，结果在模型里漏掉了 static::addGlobalScope() 这步？查出来的数据完全没受限制，到处找原因。真相是：它必须老老实实待在模型的 boot 静态方法里，放错位置就报废。

• 注册位置是 boot 方法，构造函数或其它地方都不行
• 注册顺序会影响最终 SQL——后注册的作用域会包裹在先注册的外层，类似于中间件的洋葱模型
• 要是用了软删除（SoftDeletes），Lara vel 自动帮你加上了 where deleted_at is null，你的全局作用域会套在这个条件外面，有时候意想不到地把本该查到数据给屏蔽掉了

class User extends Model{    protected static function boot()    {        parent::boot();        static::addGlobalScope(new ActiveUserScope()); // ✅ 就是这里    }}

局部作用域命名要带 scope 前缀，且只能用静态方法

不加 scope 前缀，Eloquent 就不认你是作用域；写成实例方法（public function），一调用就直接报 Call to undefined method。这事就像人认路标——走错了就找不到。

• 方法名必须以 scope 开头，比如 scopeActive()、scopeByCategory()
• 参数从第二个开始算（第一个永远是 $query），可以给可选参数，但别默认传复杂对象，省得挖坑
• 返回值必须是 $query 实例，别 return true / null / array——那是给查询构建器的，不是给作用域的

class Post extends Model{    public function scopeActive($query, $includeDraft = false)    {        $query->where('status', 'published');        if ($includeDraft) {            $query->orWhere('status', 'draft'); // ⚠️ 注意 and/or 逻辑，别搞混        }        return $query; // ✅ 必须返回    }}

withoutGlobalScope() 和 withoutScopes() 的区别很实际

想临时绕过某个全局作用域？用 withoutGlobalScope()；想彻底清空所有，包括软删除、你自定义的、第三方包加的？才用 withoutScopes()。就像打了个补丁和拆了整个房子，要看情况选。

• withoutGlobalScope(ActiveUserScope::class) 只剔除指定类的作用域，干净利落
• withoutScopes() 会连 SoftDeletes 的 where 条件也干掉，查出来的可能包含已删除的记录，要小心
• 这两个方法只对当前链式调用生效，不影响后续查询或模型的其他实例，不用担心全局污染

User::withoutGlobalScope(ActiveUserScope::class)->get(); // ✅ 只跳过 ActiveUserScopeUser::withoutScopes()->get(); // ⚠️ 所有全局作用域都没了，软删除也保不住

作用域里别直接执行 get() 或 first()

作用域的本质是“修改查询构建器”，不是“执行查询”。一旦在里面调了 $query->get()，它就变成了命令式执行，后面的 ->orderBy() 或 ->with() 全都失效——成了死胡同。

• 所有数据库操作（get、count、update）必须交给调用方决定，作用域只管登记条件
• 如果真需要预加载关联，用 $query->with(...)，别顺手加个 ->get()
• 调试时想看生成的 SQL？用 toSql()，但它只是字符串，不能和 get() 混用

// ❌ 错误：提前执行，链式中断public function scopeLatest($query){    return $query->orderBy('created_at', 'desc')->get(); // 别在这 get！}// ✅ 正确：只构建，不执行public function scopeLatest($query){    return $query->orderBy('created_at', 'desc');}

作用域最麻烦的地方不在写法，而在于它的“隐形影响力”：一个全局作用域可能让整张表的读写行为突然变样。错误往往只出现在特定分支逻辑里——比如后台导出、定时任务、API 管理端，这些地方最容易被忘记检查是否被作用域干扰。记住，写对了是锦上添花，写错了就是坑。