2nd/10_Wiki/Topics/Coding/Backend_Job_Queue_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
backend-job-queue-patterns	Job Queue 패턴 — 비동기 작업 영속화	Coding	draft	B	conceptual	2026-05-09	2026-05-09	backend queue worker async vibe-coding	language applicable_to TypeScript / BullMQ / SQS / RabbitMQ Backend		worker dead letter queue delayed job scheduled job

Job Queue 패턴

"이 작업이 결국 실행되어야 한다 — 실패해도 재시도, 사용자 응답은 즉시" 가 답. producer / queue / worker / DLQ 4단 구조 + 멱등성 + 모니터링.

📖 핵심 개념

• Producer: HTTP handler 가 요청 받자마자 enqueue, 사용자에게 202.
• Queue (broker): Redis (BullMQ), AWS SQS, RabbitMQ, Kafka 등.
• Worker: 별도 프로세스. 동시성 / 백프레셔 제어.
• DLQ (Dead Letter Queue): 최대 재시도 후에도 실패한 메시지 격리.

💻 코드 패턴

BullMQ (Redis 기반, Node)

import { Queue, Worker, QueueEvents } from 'bullmq';
const conn = { connection: { host: 'redis', port: 6379 } };

// Producer
const emailQ = new Queue('email', conn);

app.post('/api/welcome-email', async (req, res) => {
  await emailQ.add('welcome', { userId: req.body.userId }, {
    attempts: 5,
    backoff: { type: 'exponential', delay: 1000 },
    removeOnComplete: 1000,    // 마지막 1000개만 보관
    removeOnFail: false,        // 실패는 보관
  });
  res.status(202).end();
});

// Worker (별도 프로세스)
const worker = new Worker('email', async (job) => {
  if (job.name === 'welcome') {
    await sendWelcomeEmail(job.data.userId);
  }
}, {
  ...conn,
  concurrency: 10,
  limiter: { max: 100, duration: 1000 }, // 초당 100건 제한
});

worker.on('failed', (job, err) => {
  log.error('job failed', { id: job?.id, attempts: job?.attemptsMade, err });
});

Idempotent worker

async function sendWelcomeEmail(userId: string) {
  const already = await db.emails.exists({ userId, kind: 'welcome' });
  if (already) return; // 멱등
  await mailer.send(...);
  await db.emails.insert({ userId, kind: 'welcome', sentAt: new Date() });
}

Delayed / scheduled

// 1시간 뒤
await emailQ.add('reminder', data, { delay: 60 * 60 * 1000 });

// Cron — 매일 오전 9시
await emailQ.upsertJobScheduler('daily-digest', { pattern: '0 9 * * *' }, { name: 'digest', data: {} });

DLQ

worker.on('failed', async (job, err) => {
  if (job?.attemptsMade === job?.opts.attempts) {
    await dlq.add('email-dead', { original: job.data, error: err.message, jobId: job.id });
  }
});

🤔 의사결정 기준

작업	도구
짧은 (<100ms) + 사용자 응답에 결과 필요	동기 처리
외부 API 호출 (이메일, 결제, 푸시)	큐
파일 처리 / PDF 생성 / 이미지 변환	큐
이벤트 fan-out (한 이벤트 → 여러 핸들러)	Pub/Sub (Kafka, NATS)
정확한 시각 실행	스케줄러 (BullMQ scheduler / Temporal)
복잡 워크플로우 (sagas)	Temporal / Inngest

❌ 안티패턴

• HTTP 요청 안에서 큰 작업 동기 처리: 사용자 30초 대기 + timeout.
• worker 가 멱등 X: at-least-once delivery → 중복 효과.
• DLQ 없음: 영구 실패 잡 무한 retry 또는 silently drop.
• monitoring 없음: queue 길이 / 실패율 모름. 백로그 폭발.
• worker concurrency 제한 없음: DB / 외부 API 부하 폭증.
• 메시지 안에 큰 payload: 큐 메모리 폭발. ID 만 + DB/blob 보조.
• graceful shutdown 미흡: deploy 시 진행 중 잡 손실. SIGTERM 받으면 현재 잡 끝나고 종료.
• 순서 보장 가정 (대부분 큐는 FIFO 아님): 명시적 순서 필요시 partition key.

🤖 LLM 활용 힌트

• "큐 설정 + worker 멱등 + DLQ + monitoring 4종 세트" 강제.
• BullMQ / SQS / Kafka 중 어떤지 명시.

🔗 관련 문서

• Idempotent_Operations
• Backend_Retry_Strategy
• Backpressure_Patterns