Laravel查询作用域中全局作用域和局部作用域有什么区别

Laravel的查询作用域是框架提供的一种封装查询条件的便捷方式，能够让常用的查询逻辑复用，减少重复代码。其中全局作用域和局部作用域是两种核心的作用域类型，二者的定位和使用方式存在明显差异。

什么是Laravel查询作用域

查询作用域本质上是对模型查询构造器的扩展，通过定义特定的方法，把常用的查询条件封装起来，在需要的时候直接调用即可。Laravel支持两种作用域：全局作用域会在模型的所有查询中自动生效，局部作用域则需要手动调用才会生效。

全局作用域的实现与使用

全局作用域需要定义一个实现IlluminateDatabaseEloquentScope接口的类，然后在模型中注册这个作用域。全局作用域的典型使用场景是给所有查询自动添加通用的过滤条件，比如软删除、多租户数据隔离等。

定义全局作用域类

首先创建一个全局作用域类，实现apply方法，在这个方法里添加通用的查询条件：

<?php

namespace AppScopes;

use IlluminateDatabaseEloquentBuilder;
use IlluminateDatabaseEloquentModel;
use IlluminateDatabaseEloquentScope;

class ActiveUserScope implements Scope
{
    /**
     * 应用作用域到查询构造器
     *
     * @param Builder $builder
     * @param Model $model
     * @return void
     */
    public function apply(Builder $builder, Model $model)
    {
        // 自动过滤状态为激活的用户
        $builder->where('status', 1);
    }
}

在模型中注册全局作用域

在对应的模型中使用booted方法注册全局作用域，注册后该模型的所有查询都会自动带上作用域里的条件：

<?php

namespace AppModels;

use AppScopesActiveUserScope;
use IlluminateDatabaseEloquentModel;

class User extends Model
{
    /**
     * 模型启动后注册全局作用域
     *
     * @return void
     */
    protected static function booted()
    {
        static::addGlobalScope(new ActiveUserScope());
    }
}

临时移除全局作用域

如果某次查询不需要全局作用域的条件，可以使用withoutGlobalScope方法移除：

<?php

use AppModelsUser;
use AppScopesActiveUserScope;

// 移除单个全局作用域查询所有用户
$allUsers = User::withoutGlobalScope(ActiveUserScope::class)->get();

// 移除所有全局作用域
$allUsers = User::withoutGlobalScopes()->get();

局部作用域的实现与使用

局部作用域不需要单独定义类，只需要在模型里定义以scope开头的方法即可，调用时去掉scope前缀，使用驼峰命名法调用。局部作用域需要手动调用才会生效，适合封装特定场景下使用的查询条件。

定义局部作用域

在模型里定义局部作用域方法，方法接收查询构造器作为参数，然后添加对应的查询条件：

<?php

namespace AppModels;

use IlluminateDatabaseEloquentModel;

class User extends Model
{
    /**
     * 局部作用域：筛选成年用户
     *
     * @param Builder $query
     * @return Builder
     */
    public function scopeAdult($query)
    {
        return $query->where('age', '>=', 18);
    }

    /**
     * 局部作用域：筛选指定性别的用户
     *
     * @param Builder $query
     * @param string $gender
     * @return Builder
     */
    public function scopeGender($query, $gender)
    {
        return $query->where('gender', $gender);
    }
}

调用局部作用域

局部作用域通过模型查询构造器调用，支持链式调用，也可以传递参数：

<?php

use AppModelsUser;

// 调用无参数局部作用域
$adultUsers = User::adult()->get();

// 调用有参数局部作用域
$maleAdultUsers = User::adult()->gender('male')->get();

全局作用域与局部作用域的核心区别

二者的差异主要体现在生效方式、使用场景、实现复杂度等方面，具体对比如下：

使用建议

如果某类查询条件是该模型几乎所有查询都需要用到的，比如多租户场景下自动过滤当前租户的数据，优先选择全局作用域，减少重复调用的工作量。如果是仅在特定业务场景下才需要的查询条件，比如后台列表的筛选条件，优先选择局部作用域，避免不必要的条件自动生效影响查询逻辑。同时全局作用域不要定义过多，否则会导致查询逻辑不清晰，排查问题的时候增加难度。

Laravel查询作用域全局作用域局部作用域修改时间：2026-07-02 17:57:34