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.
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_jobsmonitorada, 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í.