Laravel 10中dispatchSync方法在任务失败时抛出依赖解析异常

问题复现 #

在Laravel 10中，使用dispatchSync执行实现了ShouldQueue并引入Queueable trait的任务时，一旦任务调用$this->fail()就会抛出以下异常：

Unresolvable dependency resolving [Parameter #0 [ <required> $app ]] in class Illuminate\Support\ServiceProvider

异步执行dispatch()正常，移除Queueable trait后同步执行失败也不会报错，但需要同时支持同步和队列执行。

解决方案 #

方案1：重写Job中的fail方法 #

问题根源是同步执行时，任务的失败处理逻辑尝试解析ServiceProvider的依赖，但同步环境下相关上下文未正确初始化。我们可以重写fail方法，在同步执行时跳过队列相关的失败处理逻辑：

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Throwable;

class SomeJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    private array $data;

    public function __construct(array $data = [])
    {
        $this->data = $data;
    }

    public function handle(): void
    {
        // ... 业务逻辑
        $this->fail();
    }

    /**
     * 重写fail方法，适配同步执行场景
     */
    public function fail(?Throwable $exception = null): void
    {
        // 判断是否为同步执行
        if (app()->runningInConsole() && !$this->queue) {
            // 同步执行时，仅记录异常或自定义失败逻辑，不触发队列的失败处理
            if ($exception) {
                report($exception);
            }
            return;
        }

        // 队列执行时，调用父类的fail方法
        parent::fail($exception);
    }
}

方案2：调用dispatchSync时手动捕获异常 #

如果不想修改Job类，可以在调用时手动捕获异常，避免框架抛出依赖解析错误：

try {
    SomeJob::dispatchSync($data);
} catch (\Throwable $e) {
    // 自定义失败处理，比如记录日志
    report($e);
    // 也可根据业务需求抛出自定义异常
    // throw new \App\Exceptions\TaskFailedException("任务执行失败");
}

方案3：调整任务失败触发方式 #

在同步执行场景下，不使用$this->fail()，而是直接抛出业务异常，由调用方处理：

public function handle(): void
{
    // ... 业务逻辑
    if ($businessErrorCondition) {
        throw new \RuntimeException("任务执行失败：业务条件不满足");
    }
}

调用时捕获该异常即可，这样不会触发队列的失败处理逻辑，也就不会出现依赖解析问题。

原理说明 #

Laravel 10对同步任务的失败处理逻辑做了调整，当任务实现ShouldQueue并使用Queueable trait时，同步执行失败后调用$this->fail()会尝试初始化队列相关服务提供者，但同步环境下这些服务的依赖（如$app参数）未正确绑定，导致无法解析依赖抛出异常。通过重写fail方法区分同步和队列场景，或者手动处理异常，即可规避该问题。

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