队列任务类继承修复

时间: 2025年07月04日 00:21
任务: 检查并修复各个模块的队列任务类，确保它们正确继承 UCore\Queue\QueueJob

任务概述

根据项目规范，所有队列任务类都应该继承 UCore\Queue\QueueJob 基类，而不是直接实现 Laravel 的 ShouldQueue 接口。本次任务对项目中的所有队列任务类进行了检查和修复。

检查结果

✅ 已正确继承 UCore\Queue\QueueJob 的类：

app/Module/LCache/QueueJob.php - 抽象基类，正确继承 UCore\Queue\QueueJob
app/Module/DelayQueue/Job/Job.php - 正确继承 UCore\Queue\QueueJob
app/Module/Pet/Jobs/ProcessActiveSkillsJob.php - 正确继承 UCore\Queue\QueueJob
app/Module/Farm/Jobs/CheckUserLandsAfterLoginJob.php - 正确继承 UCore\Queue\QueueJob
所有 DCache 目录下的缓存队列任务类 - 正确继承相应的基类

❌ 已修复的队列任务类（原来直接实现ShouldQueue接口）：

1. app/Module/Game/Jobs/TestJob.php

修复前: 直接实现 ShouldQueue 接口
修复后: 继承 UCore\Queue\QueueJob，实现 run() 和 payload() 方法
变更: 添加了中文注释，规范化构造函数和方法签名

2. app/Module/Ulogic/Queues/SendAppMessageQueue.php

修复前: 直接实现 ShouldQueue 接口
修复后: 继承 UCore\Queue\QueueJob，实现 run() 和 payload() 方法
变更: 保留了原有的业务逻辑，添加了错误处理和日志记录

3. app/Module/Test/Jobs/TestJob.php

修复前: 直接实现 ShouldQueue 接口
修复后: 继承 UCore\Queue\QueueJob，实现 run() 和 payload() 方法
变更: 添加了中文注释，规范化构造函数和方法签名

4. app/Module/Transfer/Jobs/RetryFailedOrderJob.php

修复前: 直接实现 ShouldQueue 接口
修复后: 继承 UCore\Queue\QueueJob，实现 run() 和 payload() 方法
变更: 将 handle() 方法改为 run() 方法，修复返回值类型，调整 failed() 方法签名

5. app/Module/Transfer/Jobs/SendCallbackJob.php

修复前: 直接实现 ShouldQueue 接口
修复后: 继承 UCore\Queue\QueueJob，实现 run() 和 payload() 方法
变更: 将 handle() 方法改为 run() 方法，修复返回值类型，保留原有业务逻辑

6. app/Module/Transfer/Jobs/ProcessTransferOrderJob.php

修复前: 直接实现 ShouldQueue 接口
修复后: 继承 UCore\Queue\QueueJob，实现 run() 和 payload() 方法
变更: 将 handle() 方法改为 run() 方法，修复返回值类型，保留原有业务逻辑

7. app/Module/Notification/Queues/SendNotificationQueue.php

修复前: 直接实现 ShouldQueue 接口
修复后: 继承 UCore\Queue\QueueJob，实现 run() 和 payload() 方法
变更: 将 handle() 方法改为 run() 方法，添加错误处理和日志记录

8. app/Module/GameItems/Jobs/TestJob.php

修复前: 直接实现 ShouldQueue 接口
修复后: 继承 UCore\Queue\QueueJob，实现 run() 和 payload() 方法
变更: 添加了中文注释，规范化构造函数和方法签名

9. app/Module/Dev/Queues/DevQueue.php

修复前: 继承不存在的 BaseQueue 类
修复后: 继承 UCore\Queue\QueueJob，实现 run() 和 payload() 方法
变更: 移除对不存在的 BaseQueue 的依赖，添加日志记录

修复内容详情

主要变更模式：

继承关系: 从 implements ShouldQueue 改为 extends QueueJob
移除 Traits: 删除 Laravel 原生的队列 traits（Dispatchable, InteractsWithQueue, Queueable, SerializesModels）
构造函数: 调用 parent::__construct() 传递任务参数
方法实现:
- 将 handle() 方法改为 run() 方法，返回 bool 类型
- 实现 payload() 方法返回任务数据
- 调整 failed() 方法签名为接受 \Throwable 参数
错误处理: 添加适当的异常处理和日志记录
导入语句: 添加必要的 use 语句，如 use Illuminate\Support\Facades\Log

技术特点：

遵循项目规范: 所有队列任务类现在都正确继承 UCore\Queue\QueueJob
保持业务逻辑: 修复过程中保留了原有的业务处理逻辑
错误处理: 增强了错误处理和日志记录功能
类型安全: 使用了严格的类型声明和返回值类型
代码规范: 添加了中文注释，提高了代码可读性

验证结果

所有修复的队列任务类现在都：

✅ 正确继承 UCore\Queue\QueueJob 基类
✅ 实现了必需的 run() 和 payload() 方法
✅ 使用正确的方法签名和返回值类型
✅ 包含适当的错误处理和日志记录
✅ 遵循项目的编码规范和架构设计

影响评估

兼容性: 修复后的队列任务类与项目的队列系统完全兼容
功能性: 保留了所有原有的业务功能
可维护性: 统一的继承结构提高了代码的可维护性
扩展性: 符合项目架构设计，便于后续功能扩展

文件清单

修复的文件：

app/Module/Game/Jobs/TestJob.php
app/Module/Ulogic/Queues/SendAppMessageQueue.php
app/Module/Test/Jobs/TestJob.php
app/Module/Transfer/Jobs/RetryFailedOrderJob.php
app/Module/Transfer/Jobs/SendCallbackJob.php
app/Module/Transfer/Jobs/ProcessTransferOrderJob.php
app/Module/Notification/Queues/SendNotificationQueue.php
app/Module/GameItems/Jobs/TestJob.php
app/Module/Dev/Queues/DevQueue.php

已确认正确的文件：

app/Module/LCache/QueueJob.php
app/Module/DelayQueue/Job/Job.php
app/Module/Pet/Jobs/ProcessActiveSkillsJob.php
app/Module/Farm/Jobs/CheckUserLandsAfterLoginJob.php
所有 DCache 目录下的缓存队列任务类

补充工作：创建队列事件基类

UCore\Queue\ShouldQueue.php

在修复队列任务类的基础上，还创建了 UCore\Queue\ShouldQueue 队列事件基类，用于统一管理队列事件监听器。

架构设计：

实现接口: LaravelShouldQueue + ShouldQueueInterface
核心方法: handle() 方法包含类似 QueueJob::handle 的逻辑
抽象方法: handleEvent() 方法供子类实现具体事件处理逻辑

功能特性：

统一的队列配置: 提供队列名称、重试次数、超时时间等配置
错误处理机制: 统一的异常处理和失败回调
日志记录: 集成项目日志系统，提供信息、警告、错误日志记录
重试策略: 支持指数退避的重试机制
事件过滤: 提供事件处理前的过滤机制
执行流程: 包含类似QueueJob的完整执行流程和日志记录
监控支持: 提供任务标签用于监控和调试

新增文件：

UCore\Queue\ShouldQueueInterface.php - 队列事件监听器接口（只包含run方法）

使用示例：

class CustomEventListener extends \UCore\Queue\ShouldQueue
{
    public $queue = 'events';
    public $tries = 5;

    public function run(object $event): bool
    {
        // 检查事件过滤
        if (!$this->shouldHandle($event)) {
            $this->logInfo('事件被过滤，跳过处理', [
                'event_class' => get_class($event)
            ]);
            return true;
        }

        // 处理事件逻辑
        $this->logInfo('处理自定义事件', [
            'event_id' => $this->getEventId($event)
        ]);

        // 具体业务逻辑
        if ($event instanceof CustomEvent) {
            $this->processCustomEvent($event);
        }

        return true;
    }

    protected function shouldHandle(object $event): bool
    {
        // 自定义过滤逻辑
        return $event instanceof CustomEvent && $event->isValid();
    }

    protected function handleFailure(\Throwable $exception): void
    {
        // 自定义失败处理
        $this->logError('事件处理失败，发送告警');
    }

    private function processCustomEvent(CustomEvent $event): void
    {
        // 具体的事件处理逻辑
    }
}

执行流程：

Laravel调用 handle(object $event) 方法
基类记录开始日志，调用子类的 run(object $event) 方法
子类在 run() 方法中实现具体的事件处理逻辑
基类记录执行结果和性能日志

设计优势：

统一架构: 为所有队列事件监听器提供统一的基础架构
可扩展性: 通过抽象方法和钩子方法支持灵活扩展
错误恢复: 完善的错误处理和重试机制
监控友好: 内置日志记录和监控标签
类型安全: 使用严格的类型声明

总结

本次任务成功完成了两个重要工作：

队列任务类修复: 修复了项目中所有不符合规范的队列任务类，确保它们都正确继承 UCore\Queue\QueueJob 基类
队列事件基类创建: 创建了 UCore\Queue\ShouldQueue 基类，为队列事件监听器提供统一的基础架构

修复过程中保持了原有的业务逻辑，增强了错误处理能力，提高了代码的规范性和可维护性。现在项目拥有了完整的队列架构体系：

UCore\Queue\QueueJob - 队列任务基类
UCore\Queue\ShouldQueue - 队列事件监听器基类
UCore\Queue\ShouldQueueInterface - 队列事件监听器接口
UCore\Queue\QueueJobInterface - 队列任务接口
UCore\Queue\JobEvent - 队列事件处理器

实际测试验证

测试UrsReferralCreatedListener迁移

成功将 UrsReferralCreatedListener 迁移到新的 ShouldQueue 基类：

修改内容：

继承关系: 从 implements ShouldQueue 改为 extends ShouldQueue
移除Traits: 删除 InteractsWithQueue trait
实现run方法: 添加 run(object $event): bool 方法
事件过滤: 实现 shouldHandle() 方法检查事件类型
失败处理: 实现 handleFailure() 方法

测试结果：

✅ 直接调用监听器测试通过
✅ 通过事件系统触发测试通过
✅ 队列任务执行成功（执行时间：555ms）
✅ 完整的日志记录和性能监控
✅ 业务逻辑正常执行（达人等级更新、DelayQueue传播）

执行日志示例：

[handle] jon run UrsReferralCreatedListener : handle
[业务] URS推荐关系创建，更新推荐人达人等级
[完成] jon run UrsReferralCreatedListener : runend-true (555.19795ms)

修复问题：

修复了 UCore\Queue\Helper 中 bcmul() 函数依赖问题
改用 round() 函数替代，提高兼容性

创建测试工具：

TestUrsReferralCreatedListenerCommand - 专用测试命令
支持直接调用和事件系统两种测试模式
提供详细的测试指导和日志查看建议

所有队列相关类现在都遵循统一的架构设计，为后续的开发和维护工作奠定了良好的基础。新架构已通过实际业务场景验证，运行稳定可靠。

040021-队列任务类继承修复.md 11 KB History Raw