ThinkPHP 8事件系统实战：用监听器解耦用户行为记录与消息通知

一、事件系统能解决什么实际问题

在MVC框架里，控制器承载了太多不属于它的职责。一个典型的注册方法往往是这样：验证数据、创建用户、发送验证邮件、记录操作日志、触发新手任务、更新统计缓存……这些“次要”逻辑像藤蔓一样缠绕在核心业务周围。时间一长，任何一个调整都可能引发连锁反应。

事件系统把这些次要逻辑从核心流程中剥离。核心业务做完后，只是抛出一个事件，比如“用户已注册”。至于这个事件发生后到底要做什么——写日志、发邮件、发优惠券、通知运营——全部交给独立的监听器去处理。控制器不需要知道有多少监听器在等着这个事件，监听器之间也互不干扰。新增一个处理逻辑就加一个监听器，移除一个需求就删掉对应监听器，核心代码完全不用改。

二、ThinkPHP 8 事件机制速览

ThinkPHP 8 的事件系统基于 `thinkEvent` 类，支持注册监听器、事件订阅、以及事件触发。基本用法是：

// 注册监听器
Event::listen('UserRegistered', 'applistenerUserRegisteredListener');

// 触发事件
Event::trigger('UserRegistered', $user);

监听器类只需要实现一个 `handle` 方法，接收事件携带的数据：

class UserRegisteredListener
{
    public function handle($user)
    {
        // 处理逻辑
    }
}

如果希望收听多个事件，可以创建一个事件订阅者类，将多个相关的事件处理集中在一个类里。框架会自动扫描 `event.php` 配置文件或者通过服务提供者注册。接下来我们直接用一个完整的用户行为模块来实践。

三、完整案例：构建可扩展的用户行为记录与通知模块

需求是这样的：当用户注册、登录、下单、修改密码时，系统需要做两件事——往 `user_logs` 表插一条行为记录，以及根据不同的行为类型发送不同的模板消息（站内信或短信）。未来很可能还会增加积分奖励、风险监控等需求。

我们把这个模块拆分成四步：定义事件类、编写监听器、注册事件、在控制器中触发。

1. 创建事件类

虽然ThinkPHP允许直接用字符串事件名，但为了代码可维护性，最好为每个事件定义一个类。在 `app/event` 目录下创建 `UserRegistered.php`：

<?php
namespace appevent;

use appmodelUser;

class UserRegistered
{
    public function __construct(public User $user)
    {
    }
}

同样创建 `UserLoggedIn.php`、`UserChangedPassword.php`、`OrderPlaced.php`，每个都封装所需的数据对象。

2. 编写监听器

行为记录和消息通知是两个独立的关注点，我们写成两个不同的监听器。

行为记录监听器 `app/listener/RecordUserAction.php`：

<?php
namespace applistener;

use thinkfacadeDb;

class RecordUserAction
{
    public function handle($event)
    {
        // 根据事件类型映射操作描述
        $actionMap = [
            'appeventUserRegistered'      => '注册账号',
            'appeventUserLoggedIn'        => '登录系统',
            'appeventUserChangedPassword' => '修改密码',
            'appeventOrderPlaced'         => '提交订单',
        ];

        $userId = $event->user->id ?? 0;
        $action = $actionMap[get_class($event)] ?? '未知操作';

        Db::table('user_logs')->insert([
            'user_id'    => $userId,
            'action'     => $action,
            'ip'         => request()->ip(),
            'created_at' => date('Y-m-d H:i:s'),
        ]);
    }
}

消息通知监听器 `app/listener/SendNotification.php`：

<?php
namespace applistener;

use thinkfacadeLog;

class SendNotification
{
    public function handle($event)
    {
        $user = $event->user;
        $eventClass = get_class($event);

        // 根据不同事件发送不同模板
        switch ($eventClass) {
            case 'appeventUserRegistered':
                // 发送欢迎短信或站内信
                // sendSms($user->mobile, '欢迎注册');
                break;
            case 'appeventOrderPlaced':
                // 发送订单确认通知
                // sendSms($user->mobile, '订单已创建');
                break;
            // 其他事件处理
        }

        // 实际项目中此处调用具体的消息服务，此处仅模拟
        Log::info("通知已发送：{$eventClass} 用户ID {$user->id}");
    }
}

3. 注册事件与监听器

在 `app/event.php` 配置文件中进行绑定（如果文件不存在就创建）：

<?php
return [
    'bind' => [
        // 事件类 => 监听器列表
        appeventUserRegistered::class      => [
            applistenerRecordUserAction::class,
            applistenerSendNotification::class,
        ],
        appeventUserLoggedIn::class        => [
            applistenerRecordUserAction::class,
        ],
        appeventUserChangedPassword::class => [
            applistenerRecordUserAction::class,
        ],
        appeventOrderPlaced::class         => [
            applistenerRecordUserAction::class,
            applistenerSendNotification::class,
        ],
    ],
];

这样当任何一个相应事件被触发时，关联的监听器就会自动执行。

4. 在控制器中触发事件

以注册功能为例，`app/controller/User.php` 中的 `register` 方法：

<?php
namespace appcontroller;

use appeventUserRegistered;
use thinkfacadeEvent;

class User
{
    public function register()
    {
        // 核心注册逻辑（验证、入库）
        $user = appmodelUser::create([...]);

        // 触发注册事件，后续的记录和通知全由监听器接手
        Event::trigger(new UserRegistered($user));

        return json(['code' => 0, 'msg' => '注册成功']);
    }
}

登录、下单等接口也只需在核心操作完成后触发对应事件。如果在未来的某天，运营想给注册用户添加一个“赠送100积分”的逻辑，开发者只需要新建一个 `GivePoints` 监听器，然后在 `event.php` 中把它加到 `UserRegistered` 的监听器列表里即可，无需触碰注册控制器代码。

四、一个更优雅的写法：事件订阅者

当监听器数量增多，每个事件都要在配置文件里挨个注册显得有些零散。ThinkPHP 支持事件订阅者，它可以把对多个事件的监听集中到一个类中，通过 `subscribe` 方法返回事件与方法的映射。

创建 `app/subscribe/UserEventSubscriber.php`：

<?php
namespace appsubscribe;

use appeventUserRegistered;
use appeventUserLoggedIn;
use appeventOrderPlaced;

class UserEventSubscriber
{
    public function onUserRegistered(UserRegistered $event)
    {
        // 行为记录
        // ...
    }

    public function onUserLoggedIn(UserLoggedIn $event)
    {
        // ...
    }

    public function onOrderPlaced(OrderPlaced $event)
    {
        // ...
    }

    public function subscribe()
    {
        return [
            UserRegistered::class => 'onUserRegistered',
            UserLoggedIn::class   => 'onUserLoggedIn',
            OrderPlaced::class    => 'onOrderPlaced',
        ];
    }
}

在 `event.php` 中只需注册订阅者：

'subscribe' => [
        appsubscribeUserEventSubscriber::class,
    ],

这样事件到处理方法的映射就全部在订阅者内部管理了。

五、事件系统的优势与注意事项

重构后，控制器的职责变得单一，每个事件监听器也可独立进行单元测试。短信服务宕机只会影响通知监听器，不会阻塞下单核心流程（如果在监听器内部加了异常捕获）。新增一个行为统计报表，只需要写一个新的监听器，不会触碰修改底层的业务代码。

不过也需要注意几点。首先，事件是同步触发的，默认情况下监听器按注册顺序同步执行。如果某个监听器很耗时，会拖慢请求响应。对于耗时任务（如发送邮件），可以将监听器内部改用队列异步执行。其次，监听器内部的异常如果未被捕获，会中断后续监听器的执行，并向上抛出影响主流程。所以最好在监听器里做必要的 `try-catch`，确保次要逻辑的故障不扩散到核心业务。

六、总结

从到处都是 `Db::table(‘user_logs’)->insert` 和 `sendSms` 的控制器，到一行 `Event::trigger` 驱动所有后续处理，这次重构让整个用户模块的扩展性上了一个台阶。ThinkPHP 8 的事件系统在保持了简单直观的 API 的同时，提供了足够灵活的注册方式。如果你的项目里也有那种随着版本迭代变得越来越臃肿的控制器方法，不妨试着把那些非核心的后置处理剥离成一个个监听器。当新的需求来临时，你只需要安静地添加一个类，然后在配置文件里挂上去，心里默念一句：“这下好改了。”