Laravel Job：如何针对特定异常重新入队或「取消失败」？

针对你遇到的「特定异常（如Guzzle 429）需要延迟重调，不想标记失败也不想让Job完成」的问题，有几个直接可行的方案，不用等到failed()钩子触发：

1. 在Job的handle()方法中主动捕获异常 #

这是最直接的方式，在Job执行逻辑的核心环节捕获目标异常，调用release()延迟重调后直接返回，完全跳过失败流程：

use GuzzleHttp\Exception\ClientException;
use Illuminate\Support\Facades\Http;

class YourApiJob implements ShouldQueue
{
    use InteractsWithQueue;

    public function handle()
    {
        try {
            // 你的业务逻辑：调用第三方API
            $response = Http::get('https://target-api.com/endpoint');
            $response->throw(); // 触发HTTP异常（包括429）
        } catch (ClientException $e) {
            // 只处理429状态码的情况
            if ($e->getResponse()->getStatusCode() === 429) {
                // 优先用服务器返回的Retry-After头，没有则用指数退避
                $retryAfter = $e->getResponse()->header('Retry-After') ?? $this->calculateExponentialBackoff();
                // 延迟重调Job
                $this->release($retryAfter);
                // 直接返回，不标记Job为完成或失败
                return;
            }
            // 其他HTTP异常继续抛出，交给框架处理失败流程
            throw $e;
        }
    }

    // 自定义指数退避计算逻辑
    private function calculateExponentialBackoff()
    {
        // 第n次重试延迟 = 2^n * 5秒，最多不超过10分钟
        $delay = pow(2, $this->attempts()) * 5;
        return min($delay, 600);
    }
}

2. 用自定义Job中间件统一处理 #

如果你有多个Job需要处理类似的429异常，可以把逻辑抽离到中间件，实现代码复用：

第一步：创建中间件 #

namespace App\Queue\Middleware;

use GuzzleHttp\Exception\ClientException;

class HandleRateLimit
{
    public function handle($job, $next)
    {
        try {
            // 执行Job的handle逻辑
            $next($job);
        } catch (ClientException $e) {
            if ($e->getResponse()->getStatusCode() === 429) {
                $retryAfter = $e->getResponse()->header('Retry-After') ?? 10;
                $job->release($retryAfter);
                return;
            }
            // 非目标异常继续抛出
            throw $e;
        }
    }
}

第二步：在Job中注册中间件 #

class YourApiJob implements ShouldQueue
{
    use InteractsWithQueue;

    public function middleware()
    {
        return [new \App\Queue\Middleware\HandleRateLimit];
    }

    // ... 你的handle逻辑
}

3. 重写Job的shouldRetry()和retryAfter()方法 #

利用Laravel原生的重试机制，通过重写这两个方法，让框架自动判断是否重调及延迟时间：

use GuzzleHttp\Exception\ClientException;
use Illuminate\Queue\InteractsWithQueue;

class YourApiJob implements ShouldQueue
{
    use InteractsWithQueue;

    // 设置最大重试次数
    public $tries = 5;

    // 决定是否对当前异常进行重试
    public function shouldRetry($exception)
    {
        return $exception instanceof ClientException && $exception->getResponse()->getStatusCode() === 429;
    }

    // 自定义重试延迟时间
    public function retryAfter()
    {
        // 指数退避：第1次等5秒，第2次10秒，第3次20秒...
        return pow(2, $this->attempts()) * 5;
    }
}

这个方案下，当Job抛出429异常时，框架会自动触发重调，不会标记为失败；如果是其他异常，直接进入失败流程。

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