PHP Laravel 队列任务如何保证失败重试不重复扣款

Laravel 队列任务要避免失败重试造成重复扣款，关键不是把 Job 标成“唯一”就结束，而是把幂等责任放在三层：订单库用唯一业务键约束同一笔支付意图，支付网关用同一个幂等键接收请求，Job 重试时先查询结果再决定是否继续。队列锁只能减少并发，不能替代支付流水和数据库约束。

重复扣款通常发生在三个边界没有对齐

一次扣款至少跨过业务数据库、Laravel queue worker 和外部支付网关。只在其中一层做去重，仍可能出现“本地看起来只执行一次，网关实际收到两次”的情况。

Laravel 的 ShouldBeUnique 适合减少相同 Job 的重复派发，但它依赖支持锁的缓存驱动，而且唯一约束不适用于批处理中的 Job。生产支付流程仍应把数据库唯一索引和网关幂等能力放在更靠后的安全边界。

先在事务里建立支付意图，再让队列处理它

下单接口里不要先 dispatch、再创建支付记录。更稳妥的顺序是：在一个数据库事务中锁定订单，创建或取得支付尝试记录，生成稳定的幂等键，事务提交后再派发 Job。下面的示例只展示边界，PaymentGateway 代表项目自己的网关适配器。

lockForUpdate()->findOrFail($orderId);

    // 业务唯一键来自订单，不要在重试时重新随机生成。
    return PaymentAttempt::query()->firstOrCreate(
        ['order_id' => $order->id],
        [
            'idempotency_key' => 'pay-order-' . $order->id,
            'status' => 'pending',
        ],
    );
});

// 事务成功提交后再入队，避免 Job 读取未提交的支付记录。
ChargePayment::dispatch($attempt->id)->afterCommit();

真实项目还应在 payment_attempts.order_id 和 payment_attempts.idempotency_key 上建立唯一索引，并处理并发请求触发的唯一键冲突。firstOrCreate 是便于理解的写法，最终一致性仍由数据库索引兜底。

重试时先查结果，不能把超时当成扣款失败

外部请求超时最危险，因为客户端不知道网关是否已经扣款。Job 可以重试，但重试动作必须是“查询优先”。本地状态为 succeeded 时直接结束；状态为 processing 或本地没有结果时，按同一个幂等键查询网关；只有网关明确返回可重试失败，才再次发送相同幂等键的扣款请求。

attemptId)->releaseAfter(10)];
    }

    public function handle(PaymentGateway $gateway): void
    {
        $attempt = PaymentAttempt::query()->findOrFail($this->attemptId);

        // 已成功的尝试不再触碰网关，重试会安全结束。
        if ($attempt->status === 'succeeded') {
            return;
        }

        // 超时或处理中先查，不把未知结果误判为失败。
        $remote = $gateway->findByIdempotencyKey($attempt->idempotency_key);
        if ($remote?->isSucceeded()) {
            $attempt->markSucceeded($remote->transactionId());
            return;
        }
        if ($remote?->isProcessing()) {
            $this->release(15);
            return;
        }

        // 网关必须按同一幂等键处理这次请求。
        $result = $gateway->charge(
            amount: $attempt->amount,
            idempotencyKey: $attempt->idempotency_key,
        );
        $attempt->recordGatewayResult($result);
    }
}

WithoutOverlapping 只是在同一时刻避免两个 worker 同时处理同一把锁。它不能证明上一次请求没有到达网关，因此 findByIdempotencyKey 和网关的幂等语义才是“不会重复扣款”的核心。

把 retry_after、timeout 和人工复核一起设计

Laravel 文档明确区分了连接的 retry_after 与 worker 的 --timeout。通常应让 worker 超时早于 retry_after，否则旧 worker 尚未退出时，队列已经把任务重新投递，两个 worker 可能同时处理同一 Job。支付任务还要根据网关最长响应时间、锁释放时间和重试次数一起设定，而不是照抄默认值。

# worker 超时要短于 queue.php 中的 retry_after。
php artisan queue:work redis --queue=payments --tries=3 --timeout=30 --backoff=10

# 只重试已经进入失败表的任务；上线前先确认幂等键仍未变。
php artisan queue:retry 

如果任务耗尽次数仍无法确认结果，应把支付尝试标记为 needs_review，记录网关请求号、最后响应和查询时间，交给人工或对账任务处理。不要在失败回调里新建一笔支付意图，也不要仅靠删除失败记录来“清理”重复风险。

常见问题

ShouldBeUnique 能不能保证不会重复扣款？

不能单独保证。它主要阻止相同唯一键的 Job 被重复派发，仍可能遇到锁过期、批处理不适用、worker 崩溃或外部请求已成功但本地未落库等情况。

网络超时后应该立即再次调用扣款接口吗？

不应该。先用原幂等键查询网关结果；查询不到时保持处理中或进入复核，只有网关明确告诉你这次请求未生效并允许重试，才发起相同幂等键的请求。

afterCommit 和数据库唯一索引都需要吗？

需要解决不同问题。afterCommit 防止队列过早读取未提交数据，唯一索引防止并发请求创建重复支付意图，二者不能互相替代。