Noções Básicas de Filas

8 exemplos para você começar com filas e workers para Node.js - 6 básicos e 2 intermediários.

Pré-requisitos

npm install bullmq ioredis
npm install -D typescript@5.6 tsx

Redis 7 é necessário para BullMQ. Veja BullMQ para configuração de worker em produção.

Exemplos Básicos

1. Por que Usar Filas?

• Usuários percebem latência do trabalho mais lento no caminho da requisição
• Workers retentam sem que o usuário espere pelo timeout do socket

Relacionado: BullMQ - Filas baseadas em Redis

2. Produtor Enfileira Job (Express 5)

import { Queue } from "bullmq";
import IORedis from "ioredis";
 
const connection = new IORedis(process.env.REDIS_URL!, { maxRetriesPerRequest: null });
const emailQueue = new Queue("email", { connection });
 
app.post("/invite", async (req, res) => {
  const job = await emailQueue.add("send-invite", {
    to: req.body.email,
    orgId: req.body.orgId,
  });
  res.status(202).json({ jobId: job.id });
});

• 202 Accepted sinaliza processamento assíncrono
• O payload do job deve ser serializável em JSON e pequeno
• Inclua ID de correlação para rastreamento

3. Worker Consome Job

import { Worker } from "bullmq";
import IORedis from "ioredis";
 
const connection = new IORedis(process.env.REDIS_URL!, { maxRetriesPerRequest: null });
 
new Worker(
  "email",
  async (job) => {
    if (job.name === "send-invite") {
      await sendInviteEmail(job.data.to, job.data.orgId);
    }
  },
  { connection, concurrency: 5 }
);

• Execute workers como um processo ou contêiner separado da API
• concurrency limita jobs paralelos por pod do worker
• Lançar um erro aciona a política de retentativa do BullMQ

4. Retentativa e Backoff

await emailQueue.add(
  "send-invite",
  { to, orgId },
  {
    attempts: 5,
    backoff: { type: "exponential", delay: 2000 },
    removeOnComplete: 1000,
    removeOnFail: false,
  }
);

• Backoff exponencial reduz o "thundering herd" em caso de indisponibilidade do fornecedor
• Mantenha jobs falhados para inspeção da DLQ (removeOnFail: false)
• Limite attempts para que mensagens venenosas parem eventualmente

Relacionado: Retentativas com Backoff

5. Endpoint de Status do Job

app.get("/jobs/:id", async (req, res) => {
  const job = await emailQueue.getJob(req.params.id);
  if (!job) return res.status(404).json({ error: "not_found" });
  const state = await job.getState();
  res.json({ id: job.id, state, progress: job.progress });
});

• Estados: waiting, active, completed, failed, delayed
• Faça polling ou use SSE/WebSocket para progresso na UI
• Não exponha traces de pilha internos na API de jobs

6. Idempotência Antes de Efeitos Colaterais

await paymentsQueue.add("capture", { paymentId, idempotencyKey }, { jobId: idempotencyKey });

• jobId estável deduz jobs duplicados de retentativas do cliente
• O worker ainda verifica a restrição de unicidade do DB antes de cobrar
• Veja Chaves de Idempotência

Exemplos Intermediários

7. Deployables Separados

api/          -> Apenas HTTP + enfileiramento
worker-email/ -> BullMQ Worker
worker-media/ -> Fila de CPU pesada

• API escala por RPS; workers escalam por profundidade da fila
• Limites de recursos diferentes (CPU para worker de imagem)
• URLs compartilhadas de Redis e Postgres via env

Relacionado: Fleet de Workers de Referência

8. Fila vs Cron

• Cron sem lock de líder executa duplicado em N pods
• Veja Agendamento e Cron

FAQs

Relacionados

• BullMQ - padrões de produção
• Consumidores AWS SQS - fila gerenciada
• Chaves de Idempotência - retentativas seguras
• Melhores Práticas de Filas - checklist de monitoramento
• Desligamento Gracioso - esvaziar workers

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.