@faapi/task-pgboss
faapi 任务子系统的 pg-boss 驱动（PostgreSQL 持久化队列）。
基于 PostgreSQL 的任务队列——任务不丢（持久化）、多实例天然防重跑（worker 领取制）、cron 重复投递由 pg-boss 消费语义兜底。复用业务方已有的 Postgres，不引入 Redis。
安装
pnpm add @faapi/task-pgboss pg-boss
使用
任务定义不变（主包文件约定 src/tasks/<name>/task.ts），只切驱动：
// faapi.config.ts
import type { FaapiConfig } from '@faapi/faapi';
export default {
task: {
driver: 'pgboss',
pgboss: { connectionString: 'postgres://localhost:5432/app' }, // 透传给 new PgBoss(...)
},
} satisfies FaapiConfig;
// handler 里用法完全不变
export function POST(body, tasks) {
return tasks.enqueue('send-email', { to: body.email });
}
语义映射
| faapi 驱动接口 | pg-boss |
|---|---|
list({ name, state, limit }) | boss.findJobs(name)（v12 起可用）：六态精确映射（created→pending、retry→retry、active→running、completed→done、failed→failed、cancelled→cancelled）；不传 name 遍历本进程已建队列；createdAt 降序截断 limit。complete 不带执行结果，done 记录无 result |
enqueue(name, payload, { retries, delayMs, dedupId }) | 幂等 createQueue(name)（每任务名每进程一次，缓存短路）→ boss.send(name, payload, { retryLimit, retryDelay: 1, retryBackoff: true, expireInSeconds, startAfter, id })。expireInSeconds 统一取 defaultExpireSeconds 兜底（默认 24h − 1s；pg-boss 12.28 前断言 expire 严格小于 24h，框架默认值留有余量）——pg-boss 以 expire_in 硬限执行，不映射会让 DDL 默认 15 分钟强杀仍在运行的长任务并重试 |
startWorker(name, { concurrency, process }) | 幂等 createQueue(name) → boss.work(name, { batchSize: concurrency }, handler)。批内任务并发执行、逐任务 complete/fail 结算——单个任务失败只消耗自己的重试额度，不毒化同批 |
stop(timeoutMs) | offWork（与 deadline 竞速，卡死任务不悬挂停机）+ boss.stop({ close: true, graceful: true, timeout })（timeout 单位毫秒）；deadline 到点 abort 在跑任务的 signal |
stopWorkers() | offWork()（不断开连接，dev 热替换重注册用） |
groups（批量记账，语义见主包 taskBatch.md） | 同库两张自建表 faapi_task_groups（批量行：计数器 + 回调声明 + 失败策略 + mode/next_index/payloads/carry）+ faapi_task_group_members（成员行：settled/outcome 幂等守卫 + member_index），首次组操作 CREATE TABLE IF NOT EXISTS + ADD COLUMN IF NOT EXISTS 幂等迁移；经 boss.getDb().executeSql 计账——落定为单条 CTE（成员行守卫翻转 + 计数递增 + serial 激活指针推进原子）。成员批量标识与序号以载荷包装随 data 存储（{ __faapiGroup, __faapiGroupIndex, __faapiPayload }，交付/查询还原）；cancelRemaining 逐成员 boss.cancel + getJobById 核实生效才落定；settleRemaining 按计数差值补齐落定 |
| 失败重试 | pg-boss 侧执行（retryLimit + retryBackoff 指数退避） |
注意：pg-boss（v10 起）不再隐式建队列（send() 对未创建队列静默返回 null）——驱动在投递/注册 worker 前自动幂等建队列，业务方无需预建。pg-boss 自身不提供执行中任务的取消信号，但 stop 超时路径会 abort taskCtx.signal（任务监听 signal 可尽快退出；仍不退出的由 expire_in 兜底结算）。
License
MIT