# @faapi/task-pgboss 中文文档

规范地址：https://npmcn.com/package/%40faapi/task-pgboss/

版本：7\.21\.0
npm 元数据更新时间：2026-10-31T23:23:44.875Z
中文译文更新时间：2026-11-01T03:11:41.733Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40faapi/task-pgboss
原文对照：https://npmcn.com/package/%40faapi/task-pgboss/?lang=original
项目主页：https://github.com/faapi/faapi#readme
源码仓库：https://github.com/faapi/faapi

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：110 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- peer 依赖：pg-boss ^12\.0\.0，@faapi/faapi ^7\.21\.0
- 首次发布：2026-09-13T05:10:52.663Z
- 最新版本发布：2026-10-31T23:23:44.590Z
- 已发布版本数：81（近 12 个月 81 个）

## 中文简介

PostgreSQL上faapi - persistent队列的pg-boss任务队列驱动

## 安装

```sh
npm install @faapi/task-pgboss
```

也可以使用：`pnpm add @faapi/task-pgboss`、`yarn add @faapi/task-pgboss`、`bun add @faapi/task-pgboss`

## README

# @faapi/task-pgboss

faapi 任务子系统的 **pg-boss 驱动**（PostgreSQL 持久化队列）。

基于 PostgreSQL 的任务队列——任务不丢（持久化）、多实例天然防重跑（worker 领取制）、cron 重复投递由 pg-boss 消费语义兜底。复用业务方已有的 Postgres，不引入 Redis。

## 安装

```bash
pnpm add @faapi/task-pgboss pg-boss
```

## 使用

任务定义不变（主包文件约定 `src/tasks/<name>/task.ts`），只切驱动：

```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;
```

```ts
// 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

## 常见问题

### @faapi/task-pgboss 是什么？

PostgreSQL上faapi - persistent队列的pg-boss任务队列驱动

### 如何安装 @faapi/task-pgboss？

在项目目录运行 npm install @faapi/task-pgboss，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：pg-boss（^12\.0\.0）、@faapi/faapi（^7\.21\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @faapi/task-pgboss 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @faapi/task-pgboss 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @faapi/task-pgboss 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @faapi/task-pgboss 可以商用吗？

@faapi/task-pgboss 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @faapi/task-pgboss 还在维护吗？

最新版本 7\.21\.0 发布于 2026/11/01（2 天前）；至今共发布 81 个版本，其中过去 12 个月发布了 81 个；首次发布于 2026/09/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。