Laravel全局作用域？查询作用域如何添加？-Laravel-PHP中文网

全局作用域自动应用于所有查询，适合强制性规则如软删除；局部作用域按需调用，封装复用查询逻辑，提升代码可读性与维护性。

laravel全局作用域？查询作用域如何添加？

Laravel的全局作用域（Global Scopes）就像给模型设定了一个默认的“滤镜”，每次查询这个模型时，这个滤镜都会自动生效，比如常见的软删除功能就是基于全局作用域实现的。而查询作用域（Query Scopes，也常称作局部作用域 Local Scopes）则更像是可按需调用的查询片段，它们允许你封装和复用特定的查询逻辑，让代码更清晰、更易读。添加查询作用域通常是在模型中定义一个以scope开头的方法，然后就可以在查询时链式调用它。

Laravel作用域：全局与局部的实践与思考

在我看来，理解Laravel的作用域机制，是写出优雅、高效数据库查询代码的关键一步。它不只是简单的语法糖，更是架构设计中的一个重要考量点。

全局作用域 (Global Scopes)

全局作用域，顾名思义，就是对某个模型的所有查询都自动生效的约束。这听起来很方便，但也正是其“隐式”的特性，让我在使用时总会多一份审慎。

为什么需要它？ 最典型的例子就是软删除（Soft Deletes）。我们不希望每次查询用户时都手动加上whereNull('deleted_at')。全局作用域就是为了解决这种“无处不在”的共同需求。多租户系统中的租户ID过滤也是一个绝佳的应用场景，确保每个租户只能看到自己的数据。

如何定义？ 定义全局作用域有两种主要方式：

基于类的方式： 创建一个实现了Illuminate\Database\Eloquent\Scope接口的类。这种方式更结构化，适合复杂的逻辑或需要在多个模型间复用的作用域。

// app/Scopes/ActiveUserScope.php
namespace App\Scopes;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

class ActiveUserScope implements Scope
{
    /**
     * Apply the scope to a given Eloquent query builder.
     */
    public function apply(Builder $builder, Model $model): void
    {
        $builder->where('status', 'active');
    }
}

登录后复制

然后在模型中注册它：

// app/Models/User.php
namespace App\Models;

use App\Scopes\ActiveUserScope;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The "booted" method of the model.
     */
    protected static function booted(): void
    {
        static::addGlobalScope(new ActiveUserScope);
    }
}

登录后复制

匿名全局作用域： 直接在模型的booted方法中使用闭包定义。这种方式更简洁，适合模型内部特有的、不需复用的简单逻辑。

// app/Models/Product.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    protected static function booted(): void
    {
        static::addGlobalScope('available', function (Builder $builder) {
            $builder->where('stock', '>', 0)->where('is_published', true);
        });
    }
}

登录后复制

我的看法： 全局作用域是把双刃剑。它能大幅减少重复代码，但如果滥用，也可能让查询行为变得不那么直观。每次User::all()，你可能需要回溯模型代码，才能知道背后到底加了哪些where条件。因此，我倾向于只在那些“几乎所有”情况下都必须应用的条件上使用它。

查询作用域 (Query Scopes / Local Scopes)

查询作用域提供了一种更灵活、更可控的方式来封装查询逻辑。它们不会自动应用，而是需要你明确地去调用。

为什么需要它？ 想象一下，你经常需要查询“活跃且管理员”的用户，或者“价格在某个范围内的已发布商品”。如果每次都手写where('status', 'active')->where('is_admin', true)，代码会变得冗长且容易出错。查询作用域就是为了解决这种“按需复用”的问题。

如何添加？ 在模型中定义一个以scope开头的方法。这个方法会接收$query实例作为第一个参数。

// app/Models/User.php
namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    // ...

    /**
     * Scope a query to only include active users.
     */
    public function scopeActive(Builder $query): void
    {
        $query->where('status', 'active');
    }

    /**
     * Scope a query to only include admin users.
     */
    public function scopeAdmin(Builder $query): void
    {
        $query->where('is_admin', true);
    }

    /**
     * Scope a query to include users by their role.
     */
    public function scopeRole(Builder $query, string $role): void
    {
        $query->where('role', $role);
    }
}

登录后复制

如何使用？ 在查询时，直接链式调用这些方法（去掉scope前缀，首字母小写）。

// 查询所有活跃的管理员用户
$activeAdmins = User::active()->admin()->get();

// 查询所有角色为'editor'的用户
$editors = User::role('editor')->get();

// 链式调用，传递参数
$activeEditors = User::active()->role('editor')->get();

登录后复制

我的看法： 局部作用域是我的首选。它们将复杂的查询逻辑封装得干净利落，提高了代码的可读性和维护性。当我看到Product::published()->inCategory('electronics')->priceBetween(100, 500)->get()这样的代码时，我能清晰地理解查询意图，而不需要深入到每个where条件中去。这大大提升了开发效率和团队协作的体验。

什么时候应该使用全局作用域，又该如何权衡利弊？

在我做项目决策的时候，选择全局作用域还是局部作用域，总是会让我停下来思考一会儿。这不仅仅是技术实现的问题，更是对业务逻辑和未来维护成本的预判。

使用全局作用域的场景：

强制性业务规则： 如果某个条件是模型数据完整性或业务逻辑的基石，无论在何处查询，都必须生效，那么全局作用域是合适的。最经典的例子就是SoftDeletes Trait，它确保你永远不会意外地查询到已“删除”的数据。
多租户系统的数据隔离： 在一个多租户应用中，每个用户（或租户）只能访问自己的数据。通过全局作用域，你可以自动为所有查询加上where('tenant_id', auth()->user()->tenant_id)，这极大地简化了开发，并降低了数据泄露的风险。
状态过滤： 比如一个Post模型，绝大部分时候我们只关心status为published的帖子。如果未发布的帖子很少需要被直接查询，那么将其设为全局作用域可以减少很多重复代码。

权衡利弊：

优点：

一致性保障： 确保某个关键条件在所有查询中都得到应用，避免遗漏。
代码精简： 避免在每个查询中重复相同的where子句。
架构清晰： 将核心的、默认的过滤逻辑集中管理。

缺点：

奇域

奇域是一个专注于中式美学的国风AI绘画创作平台

查看详情

隐式行为： 这是最大的挑战。开发者可能会忘记某个全局作用域的存在，导致查询结果与预期不符，调试起来会比较费劲。尤其是在大型团队或长期项目中，新成员可能不清楚这些“隐藏”的规则。
难以覆盖： 尽管可以通过withoutGlobalScope()或withoutGlobalScopes()来临时移除，但如果需要频繁移除，反而说明这个条件可能不适合作为全局作用域，或者设计上存在缺陷。
性能考量： 如果全局作用域的逻辑复杂，或者涉及多表关联，那么它对所有查询的性能影响都需要被评估。虽然通常情况下影响微乎其微，但在高并发场景下仍需注意。

我的建议：

在使用全局作用域时，我通常会遵循“少即是多”的原则。只在那些真正核心、几乎不可或缺的场景下使用。对于那些偶尔需要、或者在特定业务流程中才需要的过滤，我更倾向于使用局部作用域。同时，务必在文档中清晰地说明每个模型上存在的全局作用域，确保团队成员都能理解其行为。一个好的全局作用域，应该是那种你即使忘记了它的存在，也不会对业务逻辑产生重大偏差的类型。

局部作用域与全局作用域在实际项目中的最佳实践有哪些差异？

在实际的项目开发中，我对局部作用域和全局作用域的运用有着截然不同的侧重和最佳实践，这反映了它们各自的设计哲学和适用场景。

局部作用域（Local Scopes）的最佳实践：

局部作用域在我看来是构建灵活、可读性高查询链的利器。它的核心价值在于“按需调用”和“封装复用”。

封装业务语义： 将复杂的where、join或orderBy逻辑封装成具有业务意义的方法名。例如，Product::published()->inCategory('books')->orderedByPrice()->get()，这比一长串原始的查询构建器方法清晰得多。
提高可读性与维护性： 当你看到User::active()->admin()->recent()->get()时，你一眼就能明白这个查询的意图。如果业务逻辑发生变化，比如“活跃”的定义变了，你只需要修改scopeActive方法，而不需要改动所有调用它的地方。
参数化与灵活性： 局部作用域可以接受参数，这让它们非常灵活。Product::priceRange(100, 500)->get()可以轻松地查询不同价格区间的产品。
链式调用： 充分利用Laravel查询构建器的链式调用特性，将多个局部作用域组合起来，构建出高度定制化的查询，而代码依然保持简洁。
测试友好： 封装好的局部作用域更容易进行单元测试，确保其内部逻辑的正确性。

全局作用域（Global Scopes）的最佳实践：

全局作用域则更像是为模型设定了“默认行为”，它的使用需要更多的谨慎和考量。

核心业务约束： 仅用于那些对整个应用数据一致性至关重要的约束。例如，多租户系统中的tenant_id过滤，或者像SoftDeletes那样，确保所有查询默认不包含已逻辑删除的数据。这些是业务的“底线”，不应轻易被绕过。
少即是多： 一个模型上不应该有太多的全局作用域。过多的隐式过滤会大大增加代码的复杂度和调试难度。理想情况下，一个模型上的全局作用域数量应该控制在极少数，最好不超过两三个。
可移除性： 尽管是全局的，但总会有特殊情况需要绕过它。因此，设计全局作用域时要考虑到其可移除性。例如，在后台管理界面，可能需要查看所有（包括软删除的）数据，这时withoutGlobalScope()就显得尤为重要。
文档化与团队沟通： 由于其隐式性，全局作用域的存在和作用必须在项目文档中清晰地记录，并确保团队成员都了解。这有助于避免潜在的bug和误解。
避免复杂逻辑： 尽量保持全局作用域的逻辑简洁明了。如果逻辑过于复杂，或者涉及昂贵的计算，可能会对所有查询的性能产生不必要的影响。

差异总结：

简而言之，局部作用域是“按需选择”的工具箱，让你能灵活地构建特定查询；而全局作用域则是“默认规则”的守护者，它强制性地为模型的所有查询设定了基础行为。在我的开发流程中，我通常会优先考虑局部作用域，只有当某个条件真正达到了“普遍且强制”的级别时，才会慎重考虑使用全局作用域。这种区分有助于保持代码的透明度，同时兼顾了效率和可维护性。