Laravel queue middleware 怎样增加重试间隔

如果 Laravel 队列任务调用第三方接口时经常在几秒内连续失败，不要只把 worker 的尝试次数调大。增加重试间隔通常要先确定失败发生在 middleware、Job 主动释放，还是 worker 处理未捕获异常这一层。

Laravel 的队列 middleware 可以用 ThrottlesExceptions 控制两段等待：异常次数还没有达到阈值时，用 backoff() 指定延迟；达到阈值后，用构造函数的第二个参数指定下一次尝试前的等待秒数。若只是某个条件暂时不满足，也可以用 release() 直接按秒把 Job 放回队列。

官方地址：https://laravel.com/docs/queues

最常见的写法是 (new ThrottlesExceptions(10, 5 * 60))->backoff(5)：前 10 次异常之间等待 5 分钟，进入节流后同样等待 5 分钟。不要把 backoff(5) 当成 5 秒，它表示分钟。

先把“重试间隔”拆成四个可观察指标

我在排查队列积压时，最先记录的不是“这次失败了吗”，而是 attempt、异常计数、进入时间和下一次可执行时间。因为 Laravel 中几个名字相近的参数，实际控制的阶段并不一样。

这张表是配置口径，不是压测结果。实际判断时，我会把“从异常发生到下一次真正执行”的时间作为主要指标，把 attempt 和异常数作为辅助指标。

用 ThrottlesExceptions 增加两段式等待

对于会访问外部 HTTP 服务的 Job，优先使用 Laravel 自带的 Illuminate\Queue\Middleware\ThrottlesExceptions。第一个构造参数是允许抛出多少次异常后开始节流，第二个参数是进入节流后等待多少秒。

backoff(5),
        ];
    }

    /**
     * 限制这条 Job 的总重试时间，避免无限等待。
     */
    public function retryUntil(): DateTime
    {
        return now()->addMinutes(30);
    }

    public function handle(): void
    {
        // 在这里调用远程订单接口；异常交给 middleware 统一退避。
        app(\App\Services\RemoteOrderService::class)->sync($this->orderId);
    }
}

这个配置可以读成一条时间规则：异常次数未达到 10 次时，每次释放等待 5 分钟；达到 10 次后，节流窗口按 300 秒重新允许尝试。retryUntil() 是总时间边界，不会把每次等待改成 30 分钟。

按异常类型动态决定等待时间

固定等待适合规则简单的接口，但限流异常和普通业务异常通常不该使用同一个间隔。Laravel 文档中的 backoff() 可以接收闭包；闭包拿到异常后，可以为限流类异常选择更长的分钟数。

backoff(function (Throwable $throwable): int {
                // 限流异常通常需要更长的等待，普通异常使用较短退避。
                if ($throwable instanceof RateLimitedException) {
                    return $throwable->retryAfterMinutes();
                }

                return 2;
            })
            // 多个 Job 访问同一供应商时，共用一个节流桶。
            ->by('remote-order-provider'),
    ];
}

这里的指标重点是“同一供应商的失败是否被合并观察”。默认情况下，middleware 会使用 Job 类名作为缓存键；通过 by() 可以让多个 Job 共用一个限流桶。若不同供应商的速率限制互不相关，就不要为了省配置而共用键。

主动 release 时用秒数控制下一次执行

如果任务没有抛出异常，只是收到了“稍后再试”的业务结果，可以在 Job 内主动调用 release()。它的参数是秒数或时间对象，默认不传参数时会立即重新可见。

public function handle(): void
{
    $response = app(\App\Services\RemoteOrderService::class)
        ->trySync($this->orderId);

    if ($response->isRateLimited()) {
        // Retry-After 已换算成秒；没有值时使用 60 秒兜底。
        $delay = $response->retryAfterSeconds() ?? 60;
        $this->release($delay);

        return;
    }

    // 非限流结果才确认任务完成。
    $response->throwIfFailed();
}

主动 release() 仍会增加 Job 的尝试次数，所以要同时检查 tries 或 worker 的 --tries。如果“资源尚未准备好”会持续很久，只增加 release 秒数而不调整尝试预算，最终仍可能因为尝试次数耗尽而失败。

worker 级 backoff 和 retry_after 不要混用

有时不想逐个修改 Job，可以在启动 worker 时给一组任务设置默认异常退避：

# 让 Redis 队列中的未捕获异常至少等待 60 秒再尝试，最多尝试 3 次。
php artisan queue:work redis --tries=3 --backoff=60

--backoff=60 影响的是未捕获异常的 worker 级默认值；已经由 middleware 主动释放的 Job，不应简单地理解成还会再叠加一层 60 秒。

另一个容易误用的参数是 config/queue.php 连接里的 retry_after。它描述的是任务正在执行但在这段时间内没有完成、没有释放或删除时，队列连接何时把任务重新放回队列。它不是“每次异常后等待多少秒”的主要配置。对 Redis 等连接，还要让它大于 Job 合理的最长执行时间，避免任务尚未结束就被重复取出。

用时间线和数据判断配置是否合适

我会先用一条可计算的基线检查配置，而不是直接观察“队列好像没那么快失败了”。例如：

如果配置上线后仍看到连续请求，先确认异常是否真的被抛出：只有异常进入 ThrottlesExceptions 的处理路径，异常退避才有机会生效。如果是正常返回的限流结果，就需要在 Job 中主动 release($seconds)，或使用适合该限流器的 middleware。

常见问题

backoff(5) 是 5 秒还是 5 分钟？

在 ThrottlesExceptions 中它表示分钟。主动 release(5) 和 RateLimited->releaseAfter(5) 的语义则是秒，阅读代码时要结合具体 API。

只想每次异常都等 60 秒，是否必须用 ThrottlesExceptions？

不必须。可以使用 worker 的 --backoff=60 作为一组 Job 的默认值，或者在单个 Job 上提供自己的 backoff 配置。需要异常计数、阈值和共享节流桶时，再选择 ThrottlesExceptions。

为什么增加等待后 Job 还是很快再次执行？

优先检查异常类型和调用路径：任务可能是主动 release() 时传入了 0，或者只是返回了一个限流响应却没有调用 release；也可能是 worker 的另一进程仍在消费同一队列。记录 attempt、异常类别、release 秒数和队列名称，通常比只看失败日志更快定位。

应该把 retryUntil 设置得很长吗？

不建议。它是总时间预算，不是恢复能力的替代品。根据外部接口的恢复窗口、业务时效和补偿流程设置；超过窗口后，让任务失败并交给 failed_jobs 或人工补偿更容易控制。

总结一下：要增加 Laravel queue middleware 的重试间隔，先用 ThrottlesExceptions 明确异常阈值前后的两段等待；需要按异常类型区别处理时，把闭包交给 backoff()；业务上收到“稍后再试”则调用 release($seconds)。最后再用 tries、retryUntil() 和队列连接的 retry_after 检查总预算，避免“等待时间变长了，但任务仍然重复执行或永不结束”。