Laravel队列任务触发API限流异常时如何实现条件延迟重试？

问题根因 #

Laravel 队列的failed()方法是任务已经被判定为最终失败之后才触发的回调，此时框架已经完成了任务失败的收尾逻辑，解绑了任务实例的$job属性，所以你在这个方法里调用release()自然无法生效。

解决方案 #

以下提供两种兼容现有代码结构的实现方式：

方案1：父类统一捕获异常提前处理（推荐）

在抽象父类中统一包裹任务执行逻辑，在异常抛出后、任务被标记为失败前就处理限流重试，不需要改动太多现有代码：

abstract class Job implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    // 要求所有子类将原handle方法改为execute方法实现实际业务逻辑
    abstract public function execute();

    public function handle()
    {
        try {
            $this->execute();
        } catch (Throwable $e) {
            // 匹配限流重试规则
            if ($later = Str::match('~retry after (\d+)~', $e->getMessage())) {
                // 此时任务还未被标记为失败，$this->job正常绑定，可以正常调用release
                $this->release($later);
                // 不向上抛出异常，避免被框架计数为失败尝试
                return;
            }
            // 非限流异常正常抛出，走原有失败流程
            throw $e;
        }
    }

    public function failed(Throwable $e)
    {
        // 这里只处理最终失败的逻辑，比如错误日志记录、告警等
        logger()->error('任务最终执行失败', ['error' => $e->getMessage(), 'job' => static::class]);
    }
}

对应子类只需要把原来的handle方法名改为execute即可：

class SendDailyMessage extends Job
{
    public function __construct(public int $userId)
    {

    }

    public function execute()
    {
        Telegram::sendMessage($this->userId, 'message');
    }
}

方案2：failed方法中手动重发任务（零侵入子类）

如果你不想修改任何子类的现有代码，可以在failed方法中直接重新分发任务实例，设置对应的延迟时间即可：

abstract class Job implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function failed(Throwable $e)
    {
        // 匹配限流重试规则
        if ($later = Str::match('~retry after (\d+)~', $e->getMessage())) {
            // 控制重试次数，避免无限循环，优先级：任务类$tries属性 > 队列命令行--tries参数
            $maxTries = $this->tries ?? config('queue.attempts', 3);
            if ($this->attempts() < $maxTries) {
                // 提取当前任务的构造参数，重发新的任务实例
                $reflection = new ReflectionClass($this);
                $args = [];
                foreach ($reflection->getConstructor()->getParameters() as $param) {
                    $args[] = $this->{$param->getName()};
                }
                static::dispatch(...$args)->delay($later);
            }
        }
    }
}

注意事项 #

• 重试次数会受队列启动参数--tries=2的限制，如果需要单独调整某类任务的重试次数，可以直接在任务类中定义公共属性public $tries = 5;覆盖全局配置。
• 限流重试的延迟时间不要超过队列驱动配置的retry_after参数值，避免任务被重复执行。

内容的提问来源于stack exchange，提问作者Mwthreex