nestjs-queue-architect

NestJS Queue Architect - BullMQ エキスパート

メディアを多用するワークフロー向けに、堅牢でスケーラブルな BullMQ + NestJS ジョブ処理システムを設計します。

技術スタック

• BullMQ: 5.61.0（Redis ベースのジョブキュー）
• @nestjs/bullmq: 12.0.0（NestJS 12）
• @bull-board/nestjs: 6.13.1（キュー監視 UI）

プロジェクトコンテキストの確認

実装する前に、以下を確認します。

1. .agents/memory/ にキューパターンを説明するアーキテクチャファイルがあるか確認します
2. 既存のキューサービスと定数を確認します
3. [project]-queue-architect スキルを探します

コアパターン

キュー定数

export const QUEUE_NAMES = {
  VIDEO_PROCESSING: 'video-processing',
  IMAGE_PROCESSING: 'image-processing',
} as const;

export const JOB_PRIORITY = {
  HIGH: 1,    // User-facing
  NORMAL: 5,  // Standard
  LOW: 10,    // Background
} as const;

キューサービス

@Injectable()
export class VideoQueueService {
  constructor(@InjectQueue(QUEUE_NAMES.VIDEO) private queue: Queue) {}

  async addJob(data: VideoJobData) {
    return this.queue.add(JOB_TYPES.RESIZE, data, {
      priority: JOB_PRIORITY.NORMAL,
      attempts: 3,
      backoff: { type: 'exponential', delay: 2000 },
    });
  }
}

プロセッサー（WorkerHost）

@Processor(QUEUE_NAMES.VIDEO)
export class VideoProcessor extends WorkerHost {
  async process(job: Job<VideoJobData>) {
    switch (job.name) {
      case JOB_TYPES.RESIZE: return this.handleResize(job);
      case JOB_TYPES.MERGE: return this.handleMerge(job);
      default: throw new Error(`Unknown job: ${job.name}`);
    }
  }
}

主な原則

1. キューの種類ごとにサービスを1つ用意する - ジョブオプションをカプセル化します
2. switch ベースのルーティング - job.name によってルーティングします
3. 構造化されたエラー処理 - ログを記録し、WebSocket イベントを送信し、Redis にパブリッシュしてから再スローします
4. 必ずクリーンアップする - 一時ファイルは try/finally で処理します
5. 冪等なハンドラー - 安全に再試行できるようにします

キューの設定

BullModule.registerQueue({
  name: QUEUE_NAMES.VIDEO,
  defaultJobOptions: {
    attempts: 3,
    backoff: { type: 'exponential', delay: 2000 },
    removeOnComplete: 100,  // Prevent Redis bloat
    removeOnFail: 50,
  },
});

再試行戦略

ジョブタイプ	試行回数	遅延	理由
リサイズ	3	2000ms	一時的な障害
マージ	2	5000ms	リソース負荷が高い
メタデータ	2	1000ms	処理が速いため、早めに失敗させる
クリーンアップ	5	1000ms	成功させる必要がある

よくある落とし穴

• メモリリーク：removeOnComplete/Fail を必ず設定します
• タイムアウト：負荷の高いジョブには適切な timeout を設定します
• 競合状態：ハンドラーを冪等にします

---

プロセッサーの完全な例、テストパターン、Bull Board の設定、Redis pub/sub の統合については、こちらを参照してください： references/full-guide.md