Conceptos básicos de colas

8 ejemplos para empezar con colas y workers para Node.js: 6 básicos y 2 intermedios.

Prerrequisitos

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

Se requiere Redis 7 para BullMQ. Consulta BullMQ para la configuración de workers en producción.

Ejemplos básicos

1. ¿Por qué usar colas?

• Los usuarios perciben la latencia del trabajo más lento en la ruta de la solicitud
• Los workers reintentan sin que el usuario espere un tiempo de espera de socket

Relacionado: BullMQ - Colas respaldadas por Redis

2. El productor encola un trabajo (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 señala procesamiento asíncrono
• La carga útil del trabajo debe ser serializable en JSON y pequeña
• Incluye un ID de correlación para el rastreo

3. El worker consume el trabajo

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 }
);

• Ejecuta los workers como un proceso o contenedor separado de la API
• concurrency limita los trabajos paralelos por pod de worker
• Lanzar un error activa la política de reintentos de BullMQ

4. Reintento y retroceso

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

• El retroceso exponencial reduce la avalancha de solicitudes en caso de interrupción del proveedor
• Conserva los trabajos fallidos para la inspección de la DLQ (removeOnFail: false)
• Limita los attempts para que los mensajes venenosos finalmente se detengan

Relacionado: Reintentos con retroceso

5. Endpoint de estado del trabajo

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
• Sondea o usa SSE/WebSocket para el progreso de la UI
• No expongas rastreos de pila internos en la API de trabajos

6. Idempotencia antes de los efectos secundarios

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

• Un jobId estable elimina duplicados de encolamientos repetidos del cliente
• El worker sigue verificando la restricción de unicidad de la DB antes de cobrar
• Consulta Claves de idempotencia

Ejemplos intermedios

7. Despliegues separados

api/          -> Solo HTTP + encolamiento
worker-email/ -> Worker de BullMQ
worker-media/ -> cola de CPU pesada

• La API escala según las RPS; los workers escalan según la profundidad de la cola
• Diferentes límites de recursos (CPU para el worker de imágenes)
• URLs compartidas de Redis y Postgres a través de variables de entorno

Relacionado: Flota de workers de referencia

8. Cola vs. Cron

• Cron sin bloqueo de líder ejecuta duplicados en N pods
• Consulta Programación y Cron

Preguntas frecuentes

Relacionado

• BullMQ - patrones de producción
• Consumidores de AWS SQS - cola gestionada
• Claves de idempotencia - reintentos seguros
• Mejores prácticas de colas - lista de verificación de monitoreo
• Apagado elegante - drenar workers

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.