Como pausar e controlar filas no Laravel passo a passo

Informatec Digital » Recursos » Como pausar e controlar filas no Laravel passo a passo

Trabalhar com filas no Laravel é quase obrigatório em qualquer projeto minimamente sério: enviar e-mails, processar arquivos CSV, gerar PDFs, redimensionar imagens, chamar APIs externas… Se tudo isso for feito na requisição HTTP principal, o site fica lento, erros 500 aparecem e o usuário acaba encarando desesperadamente uma tela em branco.

A boa notícia é que o Laravel oferece uma infraestrutura de filas poderosa e flexível que permite delegar tarefas pesadas a processos em segundo plano, gerenciá-los por prioridade, agrupá-los em lotes, monitorá-los, tentar novamente quando falharem e até mesmo pausar temporariamente os processos para manutenção. Vamos analisar detalhadamente (e não deixar nada de fora) como tirar o máximo proveito disso, incluindo como pausar, retomar e controlar seu comportamento em produção.

Conceitos básicos: conexões, filas e drivers

Em Laravel, antes de pausar qualquer coisa, você precisa entender a diferença entre conexões de fila e as próprias filas. em config/queue.php Você tem um array connections onde você define cada backend: banco de dados, redis, beanstalkd, sqs, sincronização, nulo, failover, rabbitmq (se você adicionar), etc.

Cada conexão pode ter várias filas lógicas (nomes como default, emails, high, low, importsO atributo queue Cada conexão indica qual é a fila padrão para onde os trabalhos serão enviados caso nenhuma outra seja especificada. onQueue()Dessa forma, você pode fazer coisas como:

• Uma fila rápida Para e-mails ou transações curtas.
• Outra prioridade baixa Para tarefas demoradas, como processamento de vídeos ou relatórios extensos.
• Filas segmentadas por tipo de tarefa: imports, notificaciones, reportes, etc.

Ao iniciar o trabalhador com php artisan queue:workPor padrão, ele escuta a fila especificada como padrão na conexão selecionada. Se desejar priorizar, você pode passar várias filas separadas por vírgulas:

php artisan queue:work redis --queue=high,default,low

Dessa forma, o processo processa primeiro os e-mails de alta prioridade , depois os de prioridade padrão e somente então os de baixa prioridade , o que é crucial quando o sistema está sobrecarregado e você não quer que um relatório de 30 minutos bloqueie e-mails de alta prioridade.

Drivers de fila e pré-requisitos

O Laravel oferece uma API unificada para diversos drivers de fila , mas cada um possui suas próprias características e dependências específicas. Escolher o driver correto é crucial antes de discutir a pausa de workers.

Banco de dados de motoristas

O motorista banco de dados Ele armazena os trabalhos em uma tabela SQL (normalmente) jobsÉ fácil de configurar e perfeito para projetos pequenos ou ambientes de desenvolvimento onde você não quer se preocupar com Redis ou SQS.

Passos básicos:

• Gere a migração: php artisan queue:table (ou em versões mais recentes, vem como create_jobs_table por padrão).
• Executar migrações: php artisan migrate.
• Configurar CONEXÃO_FILA=banco_de_dados no .env e confirme em config/queue.php que 'default' => env('QUEUE_CONNECTION','database').

É conveniente e robusto o suficiente, mas com muitas filas e muito tráfego pode se tornar um gargalo , já que tudo passa pelo mesmo banco de dados relacional.

Driver Redis

O driver Redis é o padrão em produção. É rápido, suporta recursos avançados (bloqueio, limitação de taxa, bloqueios atômicos, Horizon, etc.) e escala muito bem.

Pontos importantes:

• Você precisa configurar a conexão Redis em config/database.php.
• opções serializer y compression do Redis Eles não são compatíveis com o motorista da fila.
• Se você usar Cluster RedisOs nomes das filas devem conter um símbolo de hashtag, por exemplo. {default}para que todas as chaves nessa fila caiam no mesmo slot.
• a opção block_for Isso permite que o trabalhador fique bloqueado enquanto aguarda tarefas por alguns segundos, em vez de ficar verificando continuamente: Economiza CPU e reduz as consultas ao servidor Redis.

Por exemplo:

'redis' => ,

Se você colocar bloco_para = 0O trabalhador permanece bloqueado indefinidamente até que uma tarefa fique disponível, algo a se ter em mente se você quiser que ele responda rapidamente a sinais como SIGTERM ou comandos de pausa.

Outros drivers: SQS, Beanstalkd, nulo, failover…

Além de bancos de dados e Redis, o Laravel suporta outros sistemas :

• Amazon SQSFilas gerenciadas da AWS, com suporte para FIFOGrupos de mensagens, desduplicação e configurações avançadas de visibilidade. Requer o SDK. aws/aws-sdk-php.
• Pé de feijãoMuito rápido e fácil, usando o pacote. pda/pheanstalk.
• sincronizar: executa as tarefas imediatamente No mesmo processo. Útil em desenvolvimento ou testes, mas em produção é praticamente como não usar filas.
• nuloDescarta tarefas assim que elas são "despachadas". Usado para desativar completamente o sistema de filas.
• failoverIsso permite configurar várias conexões e, se a principal falhar, o Laravel tenta passar a tarefa para a próxima da lista. Perfeito para ambientes onde a elevada disponibilidade é crítico.

No que diz respeito à pausa e retomada de processos, a lógica é praticamente a mesma, independentemente do driver, pois é gerenciada pelos comandos do Artisan e pela classe Worker , e não pelo backend da fila.

Criação de tarefas e serialização de modelos

Un Trabalho Em Laravel, é simplesmente uma classe que encapsula uma tarefa a ser executada em uma fila. Normalmente, ela é gerada com o Artisan e salva em app/Jobs.

Para criar um:

php artisan make:job ProcessPodcast

A classe gerada implementos ShouldQueue e geralmente usa características Dispatchable, InteractsWithQueue, Queueable y SerializesModelsO coração está no método. handle()que é o que o trabalhador faz quando o trabalho chega.

Um recurso particularmente poderoso é a serialização automática de modelos Eloquent . Se você aceitar um modelo no construtor do Job, o Laravel não adiciona o objeto inteiro à fila, apenas seu identificador. Quando o job é processado, ele reconstrói o modelo a partir do banco de dados com seus relacionamentos carregados.

Exemplo típico (em pseudocódigo, para evitar repeti-lo literalmente):

• Construtor recebe Podcast $podcast.
• A característica SerializesModels É responsável por salvar o ID.
• En handle(AudioProcessor $processor) Você faz o trabalho pesado (processamento de áudio, por exemplo).

Se você não quiser que os relacionamentos em um modelo sejam serializados (para que a carga útil não seja enorme), você pode usar $model->withoutRelations() ou no PHP 8 o atributo # na propriedade promovida pela construtora.

Injeção de dependência no método handle

Outra vantagem é que você pode injetar serviços diretamente no método handle (como se fosse um controlador), porque o Laravel também usa o contêiner de serviços em Jobs. Por exemplo, você pode solicitar um AudioProcessorClientes HTTP, repositórios, etc., e o framework se encarrega de resolvê-los.

Se você precisa de um controle extremamente preciso do que é chamado de handle, você pode usar Container::bindMethod() Em um provedor de serviços, você pode definir a lógica de injeção você mesmo, mas na maioria dos casos não há necessidade de complicar tanto as coisas.

Middleware de Tarefas

Assim como as rotas têm middleware, os Jobs também podem ter. middleware específico que são executados antes e depois da tarefa. Isso reduz bastante o código repetitivo nos métodos. handle() e é especialmente útil para:

• Limitação de taxa Com Redis.
• evitar sobreposições de obras que abordam o mesmo recurso.
• Exceções regulares Para APIs instáveis.
• Ignorar tarefas sob certas condições (Skip middleware).

O middleware geralmente é colocado em app/Jobs/Middleware e são retornados pelo método middleware() De Jó. Exemplo conceitual:

public function middleware(): array { return ;

Tipos especiais de trabalhos: únicos, criptografados e bloqueados.

O Laravel permite que você marque determinadas tarefas como único para garantir que duas instâncias idênticas nunca sejam enfileiradas ao mesmo tempo. Isso é conseguido implementando a interface. ShouldBeUnique o ShouldBeUniqueUntilProcessinge apoia a definição de uma chave uniqueId() e um tempo uniqueFor.

Isso é ideal para coisas como:

• Recalcular o índice de pesquisa de um produto: apenas uma vez por produto até terminar.
• Sincronizações com serviços externos que não permitem solicitações simultâneas para o mesmo recurso.

Por baixo dos panos, o Laravel usa um fechadura atômica de cache (Redis, memcached, banco de dados, etc.). Você também pode escolher o driver de cache para esse bloqueio com uniqueVia().

Além disso, existe a interface. ShouldBeEncrypted, com a qual você indica que o trabalho completo é Digite seu código antes de entrar na fila.Muito útil ao transmitir dados sensíveis que não devem ser transmitidos em texto simples pelo Redis, SQS ou pelo banco de dados.

Despachar, atrasar e executar tarefas em diferentes modos.

Assim que seu trabalho estiver definido, você o inicia com Job::dispatch() de controladores, ouvintes de eventos, comandos Artisan ou até mesmo closures. Os parâmetros que você passa para dispatch Eles vão diretamente ao construtor de Jó.

Variações interessantes:

• dispatchIf() y dispatchUnless() para condicionar a remessa em uma única linha.
• delay() para que a tarefa não possa ser processada até uma data/hora específica.
• dispatchAfterResponse() o afterResponse() en dispatch() Closures, que adiam a execução até que a resposta HTTP seja enviada, mas dentro do mesmo processo PHP.
• dispatchSync() Para executar o trabalho de forma síncrona (sem passar pela fila), mas reutilizando a mesma classe.
• Conexões especiais, como deferred o background Para executar após a resposta, no mesmo processo ou em um novo processo PHP.

Por fim, você pode especificar a conexão e a fila com métodos encadeados. onConnection() y onQueue(), seja durante o despacho ou dentro do construtor de tarefas.

Controle preciso: novas tentativas, recuo, tempos limite e tratamento de erros.

Uma parte importante do trabalho com filas no Laravel é decidir quantas vezes uma tarefa deve ser repetida , quanto tempo esperar entre as tentativas e quando considerá-la uma falha.

Opções disponíveis:

• --tries en queue:work Definir o número máximo de tentativas para todos os trabalhos desse trabalhador (a menos que o trabalho defina o seu próprio). $tries o tries()).
• $tries ou um método tries() na classe Job para controle por Job.
• retryUntil() Dizer: “Tente quantas vezes quiser até este ponto; depois disso, é fracasso.” Se coincidir com triescomando retryUntil.
• $maxExceptions Interromper o processo quando o problema for causado por exceções não tratadas repetidas.
• $timeout o --timeout Indica quantos segundos um Job pode ser executado antes que o processo de trabalho encerre o processo filho.
• $failOnTimeout Para marcar a tarefa como falhada em caso de tempo limite excedido.
• $backoff ou método backoff() Para definir o tempo de espera entre novas tentativas, mesmo com valores exponenciais.

Se uma tarefa lançar uma exceção não tratada, o Laravel irá... libera de volta para a cauda até que as tentativas configuradas se esgotem. Você pode controlar isso manualmente com release($segundos) o fail($exception) Quando você deseja marcar deliberadamente uma tarefa como reprovada.

Tarefas com falha, tabela failed_jobs e poda

Quando um Job esgota suas tentativas, ele passa a ser considerado trabalho fracassado e o Laravel o insere na tabela. failed_jobs (ou no DynamoDB, se você o configurar dessa forma). Essa tabela armazena o UUID, a conexão, a fila, o conteúdo da tarefa e a exceção que foi lançada.

Comandos úteis:

• php artisan queue:failed Para listar os que falharam.
• php artisan queue:retry <id|all> para tentar novamente.
• php artisan queue:forget <id> Para excluir um.
• php artisan queue:flush Para excluir tudo (com opção de excluir por horas em versões mais recentes).
• php artisan queue:prune-failed --hours=48 para eliminar automaticamente registros antigos.

Em Jobs, você pode definir um método. failed(Throwable $exception) Para uma limpeza adicional: notifique o usuário, reverta ações parciais, grave logs especializados, etc. Observe que uma nova instância do Job é criada para chamar a função. failed()Portanto, não confie em alterações de propriedade feitas em handle().

Agrupamento de tarefas: agrupamento de tarefas e sua combinação com strings.

Quando você precisa executar centenas ou milhares de tarefas relacionadas (por exemplo, importar um arquivo CSV gigante em partes, processar arquivos em lotes, limpar dados, etc.), é recomendável usar a funcionalidade de lotes do Laravel .

Fluxo básico:

• criar a tabela job_batches com php artisan queue:batches-table && php artisan migrate.
• Marque os trabalhos que farão parte de lotes com a característica. Batchable.
• Usar Bus::batch() Enviar um conjunto de tarefas com retornos de chamada. then, catch y finally.
• Acesse o lote de cada Job com $this->batch() e verifique se foi cancelado.
• Possibilidade de adicionar mais trabalhos a um lote em andamento com $this->batch()->add().

Os lotes se integram perfeitamente com as cadeias : você pode ter cadeias dentro de um lote ou lotes como elementos de uma cadeia maior. Isso é especialmente útil quando você deseja que várias cadeias sejam executadas "em paralelo" e acionem alguma ação quando todas forem concluídas.

Execução, prioridades e alocação de pessoal

Toda a magia das filas acontece porque você tem um ou mais trabalhadores executando o comando queue:work (o queue:listen(embora este último seja menos eficiente). Esses processos são daemons de longa duração que monitoram suas respectivas filas.

Opções principais de queue:work:

• Conexão: php artisan queue:work redis, queue:work database, etc.
• Drives: --queue=high,default,low priorizar.
• -onze: processa uma única tarefa e termina.
• –máximo de empregos: processa X tarefas e termina (para reiniciar periodicamente os trabalhadores e liberar memória).
• –tempo máximo: processa por N segundos e depois encerra.
• -dormir: segundos de espera quando não há trabalhos disponíveis.
• –pare-quando-esvaziarEsvazia a fila e a fecha corretamente (ideal em ambientes Docker ou para tarefas pontuais).
• -tempo esgotado: segundos de tempo limite por tarefa, como já mencionamos.
• -forçaPara processar tarefas mesmo se o aplicativo estiver em modo de manutenção.

Como esses processos são de longa duração, em produção um monitor de processos como o Supervisor (no Linux) é quase sempre usado para iniciar os workers X, reiniciá-los caso apresentem falhas e gerenciar os logs. Um bloco de configuração típico do Supervisor para Laravel define:

• comando com o php artisan queue:work ... betão
• numprocs para indicar quantos trabalhadores devem ser iniciados em paralelo.
• Caminhos de registro, usuário, reinicializações automáticas, etc.

Pausar e retomar filas no Laravel

Vamos ao que geralmente é importante na manutenção: como pausar os processos em fila sem interrompê-los abruptamente e sem deixar tarefas inacabadas. O Laravel oferece diversos mecanismos, alguns mais recentes, outros clássicos, para controlar isso.

Pausa: fila: sinais de pausa e interrupção

Nas versões recentes, o Laravel adiciona comandos específicos para pausar e retomar a execução de workers:

• php artisan queue:pause: instrui o sistema a parar de aceitar novas tarefas, mas a permitir que as que já estão em andamento sejam concluídas.
• php artisan queue:continue: retoma o processamento de novas tarefas de onde parou.

Esses comandos funcionam enviando sinais aos workers através do mecanismo de cache que o Laravel usa internamente. É por isso que é importante ter um driver de cache configurado corretamente (memcached, redis, banco de dados, arquivo, etc.), mesmo que sua fila de cache real seja outra.

Importante: Pausar uma fila ou um processo não cancela nem exclui tarefas já enfileiradas ; simplesmente impede que mais tarefas sejam removidas da fila enquanto a pausa estiver ativa.

Levantamento de dados sobre interrupções e seu impacto no desempenho.

Sempre que um worker termina uma tarefa, o Laravel verifica o cache em busca de sinais de reinicialização, pausa ou continuação . Isso tem um custo insignificante, mas existe. Se você estiver extremamente focado em desempenho e souber que não precisará pausar ou reiniciar workers por meio de comandos, poderá desativar essa verificação chamando:

Queue::withoutInterruptionPolling();

Ou até mesmo ajustar propriedades estáticas de Illuminate\Queue\Worker desativar toques específicos ($reiniciável, $pausávelNo entanto, se você fizer isso e depois tentar usar queue:pause o queue:restartos trabalhadores Eles não vão descobrir.É uma decisão de design que deve ser cuidadosamente considerada.

Pausar manualmente com o Supervisor ou o Docker

Além dos comandos próprios do Laravel , em ambientes de produção, os processos são frequentemente "pausados" indiretamente:

• Interrompendo o programa no Supervisor (supervisorctl stop laravel-worker:*), que mata ou impede o trabalho dos operários.
• Utilização –pare-quando-esvaziar em implantações para permitir que os trabalhadores terminem o que está na fila e, em seguida, sejam desligados.
• No Docker, permitir que o processo do contêiner com --stop-when-empty E então ele desliga.

A diferença com queue:pause Ao interromper completamente os processos, você impedirá o processamento de tarefas até que os trabalhadores sejam reiniciados. pausa interna Você pode manter os processos na memória, aguardando o comando. continueIsso é útil para implantações de reversão rápida ou períodos curtos de manutenção.

Transações de banco de dados e after_commit

Um erro clássico: despachar tarefas dentro de transações de banco de dados . Se você não tomar cuidado, o processo pode executar a tarefa antes que o commit seja feito, e o modelo ou os dados esperados podem ainda não estar no banco de dados.

Para evitar essa dança, você tem duas opções:

• Ativar 'after_commit' => true na configuração de conexão da fila. Assim, qualquer tarefa despachada dentro de uma transação é adiada internamente até ser confirmada.
• Utilize métodos por tarefa afterCommit() o beforeCommit() Ao despachar, para forçar o comportamento apenas em trabalhos específicos.

Se a transação for revertida, as tarefas despachadas durante ela são descartadas sem nunca entrar na fila, que é exatamente o que geralmente se deseja para manter a consistência.

Monitoramento, limpeza de filas e testes.

Depois de configurar e executar as filas de forma eficaz, não basta simplesmente criar tarefas e esquecer o assunto; é preciso monitorar e testar o comportamento de tudo.

Ferramentas e comandos úteis:

• queue:clear Esvaziar uma fila específica (SQS, Redis, banco de dados).
• queue:monitor para monitorar o número de tarefas em determinadas filas e acionar o evento. QueueBusy se ultrapassarem um limite.
• Eventos de emprego como Queue::before, Queue::after, Queue::looping y Queue::failing Para integrar lógica personalizada (logs, métricas, reversões, etc.).
• Falsificações em testes uso Queue::fake() y Bus::fake() Verificar se os trabalhos, sequências de tarefas ou lotes foram despachados sem realmente executá-los.

Nos testes, você pode afirmar coisas como "esta tarefa foi enfileirada X vezes" , "uma cadeia com estas tarefas foi despachada nesta ordem" ou "nenhuma tarefa específica foi enfileirada", o que proporciona muita segurança em fluxos complexos.

Com todo esse ecossistema — drivers como Redis ou SQS, jobs bem projetados, middleware para ajustes finos, batches, chains, configuração de repetição, workers gerenciados pelo Supervisor e comandos como queue:pause y queue:continue— O Laravel permite que você domine o processamento em segundo plano até o nível mais preciso, desde o envio típico de e-mails até arquiteturas de filas distribuídas com failover, garantindo que seu aplicativo continue respondendo rapidamente na camada HTTP enquanto tarefas complexas são executadas em segundo plano, sem bloquear o usuário.