Laravel Eloquent 模型：使用事件实现条件性关联预加载-php教程-PHP中文网

Laravel Eloquent 模型：使用事件实现条件性关联预加载

霞舞

发布： 2025-08-11 19:42:47

原创

415人浏览过

Laravel Eloquent 模型：使用事件实现条件性关联预加载

本文探讨了在 Laravel 中如何高效地实现模型关联的条件性预加载，以解决默认 $with 属性可能导致的性能浪费问题。针对特定场景，如用户模型仅在 domain_id 不为空时才需要加载 Domain 和 BusinessUnits 关联，文章详细介绍了如何利用 Eloquent 模型的 retrieved 事件来动态判断并加载所需关联，从而优化数据库查询，提升应用性能。

1. 问题背景与传统预加载的局限性

在 laravel eloquent 中，我们通常使用 $with 属性或在查询时使用 with() 方法来预加载模型关联，以避免 n+1 查询问题。例如，在一个 user 模型中，如果某些用户（如客户端）拥有 domain 和 businessunits 关联，而另一些用户（如员工）则没有，将这些关联直接定义在 $protected $with 数组中会导致所有用户在被查询时都尝试加载这些关联，即使它们不存在或不需要。

考虑以下 User 模型结构：

class User extends Authenticatable implements HasMedia
{
    // ... 其他属性和方法

    protected $with = [
        'domain',
        'BusinessUnits'
    ];

    public function BusinessUnits()
    {
        return $this->belongsToMany(BusinessUnit::class, 'users_business_units_pivot');
    }

    public function Domain()
    {
        return $this->belongsTo(Domain::class);
    }

    public function scopeClient($query)
    {
        return $query->whereNotNull('domain_id');
    }

    public function scopeEmployee($query)
    {
        return $query->whereNull('domain_id');
    }
}

登录后复制

这种设置的问题在于，对于每个 User 模型实例，即使其 domain_id 为空（即为员工），系统仍会尝试执行额外的查询来加载 Domain 和 BusinessUnits。这会导致不必要的数据库操作，尤其是在处理大量用户数据时，会显著降低应用性能。

开发者可能尝试在 $with 属性中直接使用条件逻辑，例如：

protected $with = [
    (!$this->domain_id) ? 'domain' : null,
    (!$this->domain_id) ? 'BusinessUnits' : null
];

登录后复制

然而，这种做法是不可行的，因为 PHP 类的属性初始化必须是常量表达式，不能包含动态逻辑或对 $this 的引用，因此会抛出 "Constant expression contains invalid operations" 错误。

2. 解决方案：利用 Eloquent 模型事件进行条件性预加载

为了实现模型关联的条件性预加载，我们可以利用 Eloquent 模型的生命周期事件，特别是 retrieved 事件。retrieved 事件在模型从数据库中取出后触发，此时模型的所有属性（包括 domain_id）都已经可用，我们可以基于这些属性进行条件判断。

核心思路：

盘古大模型

华为云推出的一系列高性能人工智能大模型

查看详情

从 $protected $with 数组中移除需要条件性加载的关联。
在模型的 boot() 方法中注册 retrieved 事件监听器。
在事件监听器中，根据模型实例的特定属性（如 domain_id）判断是否需要加载关联，并使用 load() 方法动态加载。

以下是具体的实现代码：

<?php

namespace App\Models;

use Laravel\Sanctum\HasApiTokens;
use Spatie\MediaLibrary\HasMedia;
use Illuminate\Notifications\Notifiable;
use Lab404\Impersonate\Models\Impersonate;
use Spatie\MediaLibrary\InteractsWithMedia;
use Illuminate\Database\Eloquent\Casts\AsArrayObject;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements HasMedia
{
    use Traits\BaseModelTrait;
    use Traits\ActiveTrait;

    use InteractsWithMedia;
    use Impersonate;
    use HasApiTokens;
    use Notifiable;
    use HasFactory;

    protected $hidden = [
        'password', 'remember_token',
    ];

    protected $fillable = [
        'name', 'email', 'password', 'avatar',
    ];

    protected $casts = [
        'settings' => AsArrayObject::class,
        'is_admin' => 'boolean',
    ];

    // 移除 'domain' 和 'BusinessUnits'，不再进行默认预加载
    // protected $with = [
    //     'domain',
    //     'BusinessUnits'
    // ];

    public function scopeAdmin($query)
    {
        return $query->where('is_admin', true);
    }

    public function scopeEmployee($query)
    {
        return $query->whereNull('domain_id');
    }

    public function scopeClient($query)
    {
        return $query->whereNotNull('domain_id');
    }

    public function BusinessUnits()
    {
        return $this->belongsToMany(BusinessUnit::class, 'users_business_units_pivot');
    }

    public function Domain()
    {
        return $this->belongsTo(Domain::class);
    }

    /**
     * 模型启动方法，用于注册事件监听器。
     *
     * @return void
     */
    public static function boot()
    {
        parent::boot(); // 务必调用父类的 boot 方法

        // 监听 retrieved 事件，在模型从数据库中取出后触发
        self::retrieved(function($model){
            // 只有当 domain_id 不为空时，才加载 'domain' 和 'BusinessUnits' 关联
            if($model->domain_id !== null)
            {
                 $model->load('domain', 'BusinessUnits');
            }
        });
    }
}

登录后复制

代码解析：

public static function boot(): 这是 Eloquent 模型的一个特殊方法，在模型类加载时自动调用。它是注册模型事件监听器的理想位置。
parent::boot(): 这一行至关重要，它确保了父类（Authenticatable 和 Model）中定义的任何启动逻辑也能被执行。
self::retrieved(function($model){ ... }): 这行代码注册了一个匿名函数作为 retrieved 事件的监听器。当 Eloquent 从数据库中成功检索到一个 User 模型实例时，这个匿名函数就会被执行，并且当前的模型实例会作为 $model 参数传递进来。
if($model->domain_id !== null): 在事件回调中，我们现在可以访问 $model 实例的属性，并根据 domain_id 的值进行条件判断。
$model->load('domain', 'BusinessUnits'): 如果条件满足，我们使用 load() 方法为当前的 $model 实例动态地加载指定的关联。load() 方法会执行额外的查询来获取这些关联数据，并将其附加到模型实例上。

3. 优势与注意事项

优势：

性能优化： 显著减少了不必要的数据库查询，尤其是在处理大量模型实例时，能有效提升应用程序性能。
代码清晰： 将条件加载逻辑封装在模型内部，使业务逻辑与数据加载策略更加分离。
自动化： 一旦设置，无论模型如何被检索（find(), get(), first(), paginate() 等），该条件加载逻辑都会自动生效。
灵活性： 可以根据任何模型属性或更复杂的业务逻辑来决定是否加载关联。

注意事项：

移除 $with 属性中的关联： 务必将需要条件加载的关联从 $protected $with 数组中移除，否则它们仍会被默认加载，导致重复查询或无效的性能优化。
事件开销： 尽管 retrieved 事件在每个模型实例被检索时都会触发，但其开销通常很小。只有在事件内部执行了额外的数据库查询（如 load()）时，才会产生显著的性能影响。在此场景下，这种影响是可控且有益的，因为它避免了更广泛的无条件加载。
适用场景： 这种方法最适用于模型自身包含判断关联是否需要加载的条件属性。如果条件依赖于外部上下文或复杂的业务规则，可能需要考虑其他方法，例如在资源类中进行条件加载（对于 API 响应）或使用自定义查询作用域。