Todos os artigos

· 3 min de leitura

Tire o trabalho pesado do request: filas na prática com Laravel

O que mandar para a fila, como lidar com retries, idempotência, timeouts e falhas — e por que fila sem observabilidade é só um lugar novo para perder dados.

  • Laravel
  • Filas
  • Arquitetura

Boa parte dos problemas de performance que encontro em sistemas PHP tem a mesma raiz: a requisição HTTP está fazendo trabalho demais. Envia e-mail, gera PDF, chama três APIs externas, recalcula um relatório — tudo enquanto o usuário espera a página carregar.

Filas resolvem isso, mas introduzem uma nova classe de problemas. Este é o checklist que uso quando estruturo processamento assíncrono em um projeto Laravel.

O que vai para a fila

A regra que uso: se o usuário não precisa do resultado para continuar, não precisa acontecer dentro do request.

  • Envio de e-mails, notificações e mensagens de WhatsApp
  • Chamadas a APIs externas lentas ou instáveis (ERPs, transportadoras, gateways)
  • Geração de PDFs, planilhas e relatórios
  • Sincronizações e importações em lote
  • Qualquer coisa que dependa de um serviço que pode estar fora do ar

O que não vai: validações que o usuário precisa ver na hora e operações cujo resultado aparece na próxima tela.

Jobs pequenos e focados

Um job que “processa o pedido inteiro” é difícil de reprocessar quando falha no meio. Prefiro jobs pequenos, encadeados:

Bus::chain([
    new ReservarEstoque($pedido),
    new EmitirNotaFiscal($pedido),
    new NotificarCliente($pedido),
])->catch(function (Throwable $e) use ($pedido) {
    $pedido->marcarComoPendenteDeRevisao($e->getMessage());
})->dispatch();

Se a emissão da nota falhar, o estoque já foi reservado e não será reservado de novo quando o job for reprocessado.

Idempotência: o job vai rodar mais de uma vez

Essa é a parte que mais gente esquece. Em algum momento, um job vai executar duas vezes: o worker morreu depois de processar mas antes de confirmar, o timeout estourou, alguém reprocessou manualmente.

O job precisa ser seguro para repetir:

public function handle(): void
{
    // Já processado? Não faz nada.
    if ($this->pedido->nota_fiscal_id) {
        return;
    }

    DB::transaction(function () {
        $nota = $this->emissor->emitir($this->pedido);
        $this->pedido->update(['nota_fiscal_id' => $nota->id]);
    });
}

Para garantir que dois workers não processem o mesmo item ao mesmo tempo, o middleware WithoutOverlapping ou a interface ShouldBeUnique ajudam bastante.

Retries com backoff, não em loop

Se uma API externa caiu, tentar de novo em um segundo só piora a situação. Configure tentativas com espera crescente:

class EmitirNotaFiscal implements ShouldQueue
{
    public int $tries = 5;
    public int $timeout = 60;

    public function backoff(): array
    {
        return [10, 30, 120, 600]; // segundos entre tentativas
    }
}

E diferencie erro temporário de erro permanente. Um CNPJ inválido não vai ficar válido na quinta tentativa — nesse caso, chame $this->fail() e siga em frente.

Timeouts coerentes

Um detalhe que já me custou horas de investigação: o timeout do job precisa ser menor que o retry_after da conexão da fila. Se for maior, o Laravel considera o job perdido e o entrega para outro worker enquanto o primeiro ainda está executando. Resultado: processamento duplicado.

Falhas precisam ir para algum lugar visível

Fila sem observabilidade é só um lugar novo para perder dados. No mínimo:

  • A tabela failed_jobs monitorada, com alerta quando ela cresce
  • Métricas de tamanho da fila e tempo de espera (o Horizon resolve isso bem com Redis)
  • Logs com contexto suficiente para entender qual pedido falhou e por quê

Uma fila que cresce sem parar é sintoma de que os workers não estão dando conta — e você quer descobrir isso antes do cliente.

Separe filas por prioridade

Não coloque o e-mail de redefinição de senha na mesma fila que a importação de 50 mil linhas. Filas separadas, com workers dedicados, evitam que uma tarefa pesada atrase algo que o usuário está esperando:

php artisan queue:work --queue=critica,padrao,lote

Filas foram, provavelmente, a mudança arquitetural com maior retorno que apliquei em sistemas legados. Não exigem reescrever nada: dá para começar movendo uma única operação lenta e evoluir a partir daí.