Laravel 13 队列属性与任务控制

摘要

Laravel 13 引入了队列相关的 PHP Attributes，使任务配置更加声明式。本文将深入讲解队列属性的使用，包括：

• 任务重试属性
• 超时与延迟属性
• 唯一性与防重叠属性
• 队列连接属性
• 实战案例与最佳实践

本文适合希望优化队列任务配置的 Laravel 开发者。

1. 重试属性

1.1 Tries 属性

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\Tries;

#[Tries(3)]
class ProcessPodcast implements ShouldQueue
{
    use Queueable;
    
    // 最多尝试 3 次
}

1.2 Backoff 属性

use Illuminate\Queue\Attributes\Backoff;

#[Tries(3)]
#[Backoff([10, 30, 60])]
class ProcessPodcast implements ShouldQueue
{
    // 重试间隔：10秒、30秒、60秒
}

1.3 MaxExceptions 属性

use Illuminate\Queue\Attributes\MaxExceptions;

#[MaxExceptions(3)]
class ProcessPodcast implements ShouldQueue
{
    // 最多抛出 3 次异常后失败
}

2. 超时属性

2.1 Timeout 属性

use Illuminate\Queue\Attributes\Timeout;

#[Timeout(120)]
class ProcessVideo implements ShouldQueue
{
    // 超时时间 120 秒
}

2.2 FailOnTimeout 属性

use Illuminate\Queue\Attributes\FailOnTimeout;

#[Timeout(120)]
#[FailOnTimeout]
class ProcessVideo implements ShouldQueue
{
    // 超时后标记为失败
}

3. 唯一性属性

3.1 ShouldBeUnique 属性

use Illuminate\Queue\Attributes\ShouldBeUnique;

#[ShouldBeUnique(3600)]
class GenerateReport implements ShouldQueue
{
    // 1 小时内唯一
}

3.2 WithoutOverlapping 属性

use Illuminate\Queue\Attributes\WithoutOverlapping;

#[WithoutOverlapping(300)]
class ProcessOrder implements ShouldQueue
{
    // 5 分钟内不重叠执行
}

4. 队列连接属性

4.1 OnConnection 属性

use Illuminate\Queue\Attributes\OnConnection;

#[OnConnection('redis')]
class ProcessPodcast implements ShouldQueue
{
    // 使用 Redis 连接
}

4.2 OnQueue 属性

use Illuminate\Queue\Attributes\OnQueue;

#[OnQueue('podcasts')]
class ProcessPodcast implements ShouldQueue
{
    // 使用 podcasts 队列
}

4.3 组合使用

#[OnConnection('redis')]
#[OnQueue('podcasts')]
#[Tries(3)]
#[Timeout(120)]
class ProcessPodcast implements ShouldQueue
{
    use Queueable;
}

5. 完整示例

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Backoff;
use Illuminate\Queue\Attributes\Timeout;
use Illuminate\Queue\Attributes\FailOnTimeout;
use Illuminate\Queue\Attributes\OnConnection;
use Illuminate\Queue\Attributes\OnQueue;
use Illuminate\Queue\Attributes\ShouldBeUnique;

#[OnConnection('redis')]
#[OnQueue('podcasts')]
#[Tries(3)]
#[Backoff([10, 30, 60])]
#[Timeout(300)]
#[FailOnTimeout]
#[ShouldBeUnique(3600)]
class ProcessPodcast implements ShouldQueue
{
    use Queueable;
    
    public function __construct(
        public int $podcastId
    ) {}
    
    public function handle(): void
    {
        // 处理播客
    }
    
    public function uniqueId(): string
    {
        return (string) $this->podcastId;
    }
}

6. 最佳实践

6.1 合理设置重试

// CPU 密集型任务：少重试
#[Tries(2)]
#[Backoff([30, 60])]

// I/O 密集型任务：多重试
#[Tries(5)]
#[Backoff([5, 10, 30, 60, 120])]

6.2 超时设置

// 根据任务复杂度设置
#[Timeout(60)]   // 简单任务
#[Timeout(300)]  // 中等任务
#[Timeout(1800)] // 复杂任务

7. 总结

Laravel 13 的队列属性提供了声明式的任务配置：

1. 重试控制：Tries、Backoff、MaxExceptions
2. 超时控制：Timeout、FailOnTimeout
3. 唯一性：ShouldBeUnique、WithoutOverlapping
4. 连接配置：OnConnection、OnQueue

通过本指南，您已经掌握了队列属性的核心用法。

参考资料

• Laravel 13 队列文档
• PHP 8 Attributes