Laravel Eloquent的模型事件：在创建、更新、删除时触发业务逻辑与Side Effects

Laravel Eloquent 模型事件：触发业务逻辑与 Side Effects

大家好，今天我们来深入探讨 Laravel Eloquent 模型事件，以及如何利用它们在数据创建、更新、删除等操作时触发业务逻辑和处理 Side Effects。Eloquent 模型事件是 Laravel 框架中一个强大的特性，它允许我们在模型生命周期的特定阶段执行自定义代码，实现数据的自动化处理、审计跟踪、缓存失效等功能。

1. 什么是 Eloquent 模型事件？

Eloquent 模型事件是指在模型生命周期中发生的特定事件，例如模型的创建、更新、删除、保存、恢复等。Laravel 提供了一组预定义的事件，我们可以监听这些事件，并在事件发生时执行自定义的回调函数。

2. Laravel 提供的模型事件

以下表格列出了 Laravel 提供的常用模型事件：

事件名称	触发时机
creating	在模型即将被创建之前触发。如果回调函数返回 false，则创建操作将被取消。
created	在模型被成功创建之后触发。
updating	在模型即将被更新之前触发。如果回调函数返回 false，则更新操作将被取消。
updated	在模型被成功更新之后触发。
saving	在模型即将被保存（创建或更新）之前触发。如果回调函数返回 false，则保存操作将被取消。
saved	在模型被成功保存（创建或更新）之后触发。
deleting	在模型即将被删除之前触发。如果回调函数返回 false，则删除操作将被取消。
deleted	在模型被成功删除之后触发。
restoring	在软删除模型即将被恢复之前触发。如果回调函数返回 false，则恢复操作将被取消。
restored	在软删除模型被成功恢复之后触发。
retrieved	在模型从数据库中被检索之后触发。
forceDeleting	在模型即将被永久删除之前触发。如果回调函数返回 false，则永久删除操作将被取消。(需要 SoftDeletes trait)

除了这些预定义的事件之外，我们还可以自定义事件，并在需要的时候手动触发。

3. 如何监听和处理模型事件？

有多种方法可以监听和处理模型事件：

• 在模型类中定义事件方法: 这是最常用的方法，直接在模型类中定义与事件名称对应的方法。

• 使用事件监听器类: 创建一个独立的事件监听器类，并在该类中定义处理事件的逻辑。

• 使用闭包: 直接在模型类的 boot 方法中使用闭包来监听事件。

3.1 在模型类中定义事件方法

这是最常见的方式，简单直接。例如，我们有一个 Post 模型，想要在创建新文章时自动设置 slug 字段：

<?php

namespace AppModels;

use IlluminateDatabaseEloquentModel;
use IlluminateSupportStr;

class Post extends Model
{
    protected $fillable = ['title', 'content'];

    protected static function booted()
    {
        static::creating(function ($post) {
            $post->slug = Str::slug($post->title);
        });
    }
}

在这个例子中，我们使用了 creating 事件。当一个新的 Post 模型即将被创建时，creating 事件会被触发，并执行我们定义的回调函数。回调函数接收当前的模型实例作为参数，我们可以在函数内部修改模型的属性，例如设置 slug 字段。 booted 方法会在模型启动时被调用，在这里注册事件监听器。

3.2 使用事件监听器类

如果事件处理逻辑比较复杂，或者需要在多个地方重用，可以考虑使用事件监听器类。

首先，创建一个事件监听器类：

<?php

namespace AppListeners;

use AppModelsPost;

class PostCreatedListener
{
    /**
     * Handle the event.
     *
     * @param  AppModelsPost  $post
     * @return void
     */
    public function handle(Post $post)
    {
        // 在文章创建成功后，发送通知给管理员
        // 例如：Mail::to('[email protected]')->send(new NewPostNotification($post));

        // 记录日志
        Log::info('新文章创建：' . $post->title);
    }
}

然后，在 EventServiceProvider 中注册事件监听器：

<?php

namespace AppProviders;

use AppListenersPostCreatedListener;
use AppModelsPost;
use IlluminateFoundationSupportProvidersEventServiceProvider as ServiceProvider;

class EventServiceProvider extends ServiceProvider
{
    /**
     * The event listener mappings for the application.
     *
     * @var array
     */
    protected $listen = [
        AppEventsPostCreated::class => [ // 如果你创建了自己的事件
            AppListenersPostCreatedListener::class,
        ],
        Post::class => [
            'created' => [PostCreatedListener::class . '@handle'], // 使用Eloquent事件
        ]
    ];

    /**
     * Register any events for your application.
     *
     * @return void
     */
    public function boot()
    {
        parent::boot();

        //
    }
}

在这个例子中，我们将 Post 模型的 created 事件映射到 PostCreatedListener 类的 handle 方法。当 Post 模型被成功创建后，PostCreatedListener 类的 handle 方法会被调用。

注意： Laravel 10 以上版本，对 Eloquent 事件的监听器注册方式有所改变，更推荐使用数组方式进行注册，也就是上方代码中的 Post::class => ['created' => [PostCreatedListener::class . '@handle'],] 。 当然你也可以使用事件类，例如 AppEventsPostCreated::class 这需要你手动触发 event(new AppEventsPostCreated($post));。 这里使用了 PostCreatedListener::class . '@handle' ，是为了兼容一些老版本写法。 更好的写法是 [PostCreatedListener::class, 'handle']

3.3 使用闭包

如果事件处理逻辑比较简单，可以直接在模型类的 boot 方法中使用闭包来监听事件。

<?php

namespace AppModels;

use IlluminateDatabaseEloquentModel;
use IlluminateSupportFacadesCache;

class Category extends Model
{
    protected $fillable = ['name'];

    protected static function booted()
    {
        static::created(function ($category) {
            // 清除缓存
            Cache::forget('categories');
        });

        static::updated(function ($category) {
            // 清除缓存
            Cache::forget('categories');
        });

        static::deleted(function ($category) {
            // 清除缓存
            Cache::forget('categories');
        });
    }
}

在这个例子中，我们在 Category 模型的 created、updated 和 deleted 事件中都使用了闭包来清除缓存。

4. 模型事件的应用场景

Eloquent 模型事件可以应用于各种场景，以下是一些常见的例子：

• 自动设置字段值： 例如，在创建用户时自动生成 API Token，或在创建文章时自动设置 Slug。

• 发送通知： 例如，在用户注册成功后发送欢迎邮件，或在文章发布后通知管理员。

• 记录日志： 例如，记录用户的登录信息，或记录数据的修改历史。

• 缓存失效： 例如，在数据更新后清除缓存，以保证数据的一致性。

• 数据验证： 在保存模型之前，进行自定义数据验证，防止不符合规范的数据入库。

• 关联数据处理： 在删除父模型时，自动删除相关的子模型。

5. 示例：使用模型事件实现审计跟踪

这是一个比较完整的例子，演示如何使用模型事件来实现审计跟踪。

首先，创建一个 AuditLog 模型：

<?php

namespace AppModels;

use IlluminateDatabaseEloquentModel;

class AuditLog extends Model
{
    protected $fillable = [
        'user_id',
        'model_type',
        'model_id',
        'event',
        'old_values',
        'new_values',
        'ip_address',
        'user_agent',
    ];

    protected $casts = [
        'old_values' => 'array',
        'new_values' => 'array',
    ];

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

然后，创建一个 AuditTrail trait：

<?php

namespace AppTraits;

use AppModelsAuditLog;
use IlluminateSupportFacadesAuth;
use IlluminateSupportFacadesRequest;

trait AuditTrail
{
    public static function bootAuditTrail()
    {
        static::created(function ($model) {
            self::auditLog($model, 'created');
        });

        static::updated(function ($model) {
            $changes = $model->getChanges();
            // 移除 updated_at 字段，避免每次更新都记录
            unset($changes['updated_at']);

            if (!empty($changes)) {
                self::auditLog($model, 'updated', $model->getOriginal(), $changes);
            }
        });

        static::deleted(function ($model) {
            self::auditLog($model, 'deleted', $model->getOriginal());
        });
    }

    private static function auditLog($model, $event, $oldValues = [], $newValues = [])
    {
        AuditLog::create([
            'user_id' => Auth::id(),
            'model_type' => get_class($model),
            'model_id' => $model->id,
            'event' => $event,
            'old_values' => $oldValues,
            'new_values' => $newValues,
            'ip_address' => Request::ip(),
            'user_agent' => Request::userAgent(),
        ]);
    }
}

最后，在需要进行审计跟踪的模型中使用该 trait：

<?php

namespace AppModels;

use AppTraitsAuditTrail;
use IlluminateDatabaseEloquentModel;

class Product extends Model
{
    use AuditTrail;

    protected $fillable = ['name', 'price', 'description'];
}

在这个例子中，我们创建了一个 AuditLog 模型来存储审计日志。AuditTrail trait 包含了审计跟踪的逻辑，它监听了 created、updated 和 deleted 事件，并在事件发生时创建一条审计日志。我们只需要在需要进行审计跟踪的模型中使用 AuditTrail trait 即可。getOriginal() 方法可以获取模型在更新之前的原始数据。

6. 模型事件的注意事项

• 避免在事件处理程序中执行复杂的业务逻辑： 事件处理程序应该尽可能简单，只执行必要的任务。如果需要执行复杂的业务逻辑，应该将其放到队列中异步处理，避免阻塞主进程。

• 注意循环调用： 在事件处理程序中修改模型可能会触发其他事件，导致循环调用。应该避免这种情况发生。

• 事务处理： 如果需要在事件处理程序中执行数据库操作，应该使用事务来保证数据的一致性。

• 性能优化： 过多的事件监听器会影响性能。应该只监听必要的事件，并优化事件处理程序的代码。

• 使用 static::disableEvents() 和 static::enableEvents() 临时禁用事件： 在某些情况下，你可能需要在代码中临时禁用模型事件，例如在批量导入数据时。可以使用 static::disableEvents() 方法禁用事件，使用 static::enableEvents() 方法重新启用事件。

Product::disableEvents();

// 执行一些操作，例如批量导入数据

Product::enableEvents();

• 使用 withoutEvents() 执行操作而不触发事件： 你可以使用 withoutEvents() 方法来执行操作而不触发事件。

Product::withoutEvents(function () {
    // 执行一些操作，例如更新模型的属性
    $product = Product::find(1);
    $product->name = 'New Name';
    $product->save();
});

7. 错误处理与异常情况

在模型事件处理程序中，良好的错误处理至关重要。未处理的异常可能导致应用程序崩溃或数据不一致。以下是一些最佳实践：

• 使用 try-catch 块： 在事件处理程序中，将可能抛出异常的代码块包裹在 try-catch 块中，以便捕获和处理异常。

• 记录错误日志： 使用 Log::error() 方法记录错误信息，包括异常类型、错误消息、堆栈跟踪等。这有助于诊断和解决问题。

• 回滚事务： 如果事件处理程序涉及到数据库操作，并且发生了异常，应该回滚事务，以避免数据不一致。

• 通知开发者： 在发生严重错误时，可以通过邮件、短信等方式通知开发者，以便及时处理。

<?php

namespace AppListeners;

use AppModelsPost;
use IlluminateSupportFacadesLog;
use IlluminateSupportFacadesDB;

class PostCreatedListener
{
    public function handle(Post $post)
    {
        DB::beginTransaction();
        try {
            // 一些可能抛出异常的代码
            // 例如：发送通知，更新其他模型等

            // 提交事务
            DB::commit();
        } catch (Exception $e) {
            // 回滚事务
            DB::rollback();

            // 记录错误日志
            Log::error('创建文章失败：' . $e->getMessage(), ['exception' => $e]);

            // 通知开发者
            // Mail::to('[email protected]')->send(new ErrorNotification($e));

            // 可以选择抛出异常，让上层处理
            throw $e;
        }
    }
}

8. 模型观察者 (Model Observers)

Laravel 提供了一种更简洁的方式来组织模型事件监听器，即使用模型观察者。模型观察者是一个类，它包含了所有与特定模型相关的事件处理方法。

首先，创建一个模型观察者类：

<?php

namespace AppObservers;

use AppModelsPost;
use IlluminateSupportStr;

class PostObserver
{
    /**
     * Handle the Post "creating" event.
     *
     * @param  AppModelsPost  $post
     * @return void
     */
    public function creating(Post $post)
    {
        $post->slug = Str::slug($post->title);
    }

    /**
     * Handle the Post "updating" event.
     *
     * @param  AppModelsPost  $post
     * @return void
     */
    public function updating(Post $post)
    {
        // 例如：检查文章是否被审核通过，如果审核通过，则不允许修改
        // if ($post->is_approved) {
        //     throw new Exception('审核通过的文章不允许修改');
        // }
    }

     /**
     * Handle the Post "deleting" event.
     *
     * @param  AppModelsPost  $post
     * @return void
     */
    public function deleting(Post $post)
    {
       // 例如：删除文章时，同时删除相关的评论
       // $post->comments()->delete();
    }
}

然后，在 EventServiceProvider 中注册模型观察者：

<?php

namespace AppProviders;

use AppModelsPost;
use AppObserversPostObserver;
use IlluminateFoundationSupportProvidersEventServiceProvider as ServiceProvider;

class EventServiceProvider extends ServiceProvider
{
    /**
     * The event listener mappings for the application.
     *
     * @var array
     */
    protected $listen = [
        //
    ];

    /**
     * Register any events for your application.
     *
     * @return void
     */
    public function boot()
    {
        parent::boot();

        Post::observe(PostObserver::class);
    }
}

模型观察者提供了一种更清晰、更易于维护的方式来管理模型事件监听器。

9. Eloquent 模型事件的局限性

尽管 Eloquent 模型事件非常强大，但也存在一些局限性：

• 紧耦合： 事件处理逻辑与模型紧密耦合，可能会导致代码难以测试和维护。

• 性能影响： 过多的事件监听器会影响性能，特别是对于高流量的应用程序。

• 不易调试： 事件处理程序通常在后台运行，不易调试。

在设计应用程序时，应该权衡使用模型事件的利弊，并选择最适合的解决方案。

总结：

Eloquent 模型事件提供了一种便捷的方式来在模型生命周期的各个阶段执行自定义代码，实现数据的自动化处理、审计跟踪、缓存失效等功能。 通过监听特定的事件，我们可以对模型进行修改，触发其他操作，或者记录相关信息。 但是，我们也要注意事件的性能影响，错误处理，以及避免循环调用等问题，并选择合适的方式来管理事件监听器，例如使用模型观察者。