bullmq

BullMQ 队列任务开发指南

技术栈

• 队列系统: BullMQ v5.16.0+
• 类型安全: TypeScript + Zod 运行时验证
• Effect 集成: Effect 系统封装（Promise → Effect）
• Redis: ioredis (maxRetriesPerRequest: null)
• UI 监控: Bull Board (Hono adapter)

文件结构

src/lib/
├── enums/bullmq.ts                      # 队列和任务名称枚举
├── infrastructure/
│   ├── bullmq/
│   │   └── job-registry.ts              # 类型映射和 Zod 验证
│   ├── bullmq-adapter.ts                # QueueManager 核心类
│   └── effect/services/bullmq.ts        # Effect Layer
│   └── bootstrap.ts                     # Worker 注册位置
src/routes/admin/
└── queue-board.index.ts                 # Bull Board UI 路由

核心规则（MANDATORY）

三层类型安全架构

1. 编译时约束：QueueJobsMapping 确保队列只能使用特定 job name
2. 类型推断：JobDefinitionRegistry 自动推断 job data 类型
3. 运行时验证：JobSchemaRegistry 使用 Zod 验证数据

命名约定

• 队列名称：小写字母（email、cleanup，不用 EMAIL_QUEUE）
• 任务名称：kebab-case（send-welcome、daily-cleanup）
• 常量枚举：对象字面量 + as const（不用 enum）
• 索引签名：[JobName.XXX]: Schema 形式

数据验证规则

• 所有 job data 必须有对应的 Zod schema
• Schema 必须包含中文错误消息
• 日期格式：ISO 8601 字符串（2024-01-01T00:00:00Z）
• 日期字符串：YYYY-MM-DD 格式
• UUID：使用 z.uuid() 验证

Effect 使用规范

• 所有异步操作使用 Effect 封装（Effect.tryPromise）
• 同步操作使用 Effect.sync
• 错误统一返回 Error 类型
• Worker 注册使用 Effect.sync（立即返回 Worker 实例）

开发步骤

1. 添加新队列

参考 queue-definition.md

1. 在 src/lib/enums/bullmq.ts 添加队列名称
2. 在 job-registry.ts 创建 QueueJobsMapping 映射（初始为 never）
3. 注册 Worker（见步骤 3）

2. 添加新任务类型

参考 job-definition.md

1. 在 src/lib/enums/bullmq.ts 添加任务名称
2. 在 job-registry.ts 创建 Zod schema
3. 更新 JobDefinitionRegistry 类型映射
4. 更新 JobSchemaRegistry 验证映射
5. 更新 QueueJobsMapping 关联队列

3. 注册 Worker

参考 worker-registration.md

1. 在应用启动时调用 queueManager.registerWorker
2. 实现 processor 函数（接收 Job<T> 类型）
3. 可选配置：并发数、限流、重试策略
4. Worker 自动验证 job data（无需手动验证）

4. 添加任务到队列

在业务代码中使用（无需创建文件）：