# @algoan/pubsub 中文文档

规范地址：https://npmcn.com/package/%40algoan/pubsub/

版本：6\.4\.3
npm 元数据更新时间：2026-10-21T16:19:02.466Z
中文译文更新时间：2026-11-05T22:35:13.177Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：38 kB，24 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：^22\.13\.0 \|\| \>=24
- 运行依赖：3 个
- 首次发布：2020-04-15T13:58:06.142Z
- 最新版本发布：2026-10-21T16:19:02.114Z
- 近 30 天下载量：11799（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 5 个）

## 中文简介

用于 algoan 的 PubSub 图书馆

## 安装

```sh
npm install @algoan/pubsub
```

也可以使用：`pnpm add @algoan/pubsub`、`yarn add @algoan/pubsub`、`bun add @algoan/pubsub`

## README

# 普贝

这是普布Sub工厂的通称 揭露一种听觉和放电方法.

_页:1_: 今天,仅限 [Google Cloud PubSub (Google Cloud PubSub) (英语)](https://cloud.google.com/pubsub/docs/overview) 已添加.

## 安装

```bash
npm install --save @algoan/pubsub
```

## 使用量

### Google Cloud PubSub (Google Cloud PubSub) (英语)

#### 运行测试

要进行测试或尝试 PubSubFactory 类,您需要有一个google 账户并安装了 gcloud sdk.

然后,安装 [Google PubSub 模拟器](https://cloud.google.com/pubsub/docs/emulator),运行 :

```shell
gcloud components install pubsub-emulator
gcloud components install beta
gcloud components update
```

开始运行测试 :

```shell
npm test
```

将推出Google PubSub模拟器 [google-pubsub 模拟器](https://github.com/ert78gb/google-pubsub-emulator) 图书馆.

#### 示例

使用 Google 云创建 PubSub 实例 :

```typescript
import { EmittedMessage, GCPubSub, PubSubFactory, Transport } from '@algoan/pubsub'

const pubsub: GCPubSub = PubSubFactory.create({
  transport: Transport.GOOGLE_PUBSUB,
  options: {
    projectId: 'test',
    // And all other Google PubSub properties
  }
});
const topicName: string = 'some_topic';

await pubsub.listen(topicName, {
  autoAck: true,
  onMessage: (data: EmittedMessage<{foo: string}>) => {
    console.log(data.parsedData); // { foo: 'bar', time: {Date.now}, _eventName: 'some_topic' }
    // do whatever you want. The message has already been acknowledged
  },
  onError: (error: Error) => {
    // Handle error as you wish
  }
});

await pubsub.emit(topicName, { foo: 'bar' });
```

### 捐款

感谢您未来的贡献 请跟随 [这些指示](https://npmcn.com/package/%40algoan/pubsub/CONTRIBUTING.md) 在启动拉力请求之前!

## API 密码

### `PubSubFactory.create({ transport, options })`

唯一的静态方法 `PubSubFactory` 课。 它根据具体情况启动一个新的PubSub实例 `transport`。默认情况下,它连接到 [Google Cloud PubSub (Google Cloud PubSub) (英语)](https://googleapis.dev/nodejs/pubsub/latest/index.html)。 。 。 .

-   `transport`:用PubSub技术. 仅 `GOOGLE_PUBSUB` 现在已经可以使用.
-   `options`: 与运输有关的选项.
    -   若为 `transport === Transport.GOOGLE_PUBSUB`,然后来看看 [谷歌 Cloud PubSub 配置客户端](https://googleapis.dev/nodejs/pubsub/latest/global.html#ClientConfig)。 。 。 .
    -   `debug`: 如果设置为真, 显示日志 。 它使用一个 [皮诺伐木机](https://getpino.io/#/) 财务报告和审定财务报表 [皮诺色](https://github.com/pinojs/pino-pretty) 若为 `NODE_ENV` 不等同于 `production`。 。 。 .
    -   `pinoOptions`: 如果 `debug` 设置为真,设置为 [皮诺日志选项](https://getpino.io/#/docs/api?id=options)默认为 `level: debug` 财务报告和审定财务报表 `prettyPrint: true` 若为 `NODE_ENV` 不等同于 `production`。 。 。 .
    -   `topicsPrefix`: 在所有创建的主题中添加前缀. 示例 `topicsPrefix: 'my-topic'`,所有主题都将从 `my-topic+{your topic name}`。 。 。 .
    -   `topicsSeparator`: 自定义主题前缀和主题名之间的分隔符. 示例 `topicsSeparator: '-'`,所有的主题将是 `{topic prefix}-{your topic name} (default to '+')`。 。 。 .
    -   `subscriptionsPrefix`: 在所有已创建的订阅中添加前缀. 示例 `subscriptionsPrefix: 'my-sub'`,所有订阅从 `my-sub%{your topic name}`。 。 。 .
    -   `subscriptionsSeparator`: 自定义订阅和话题名之间的分隔符。 示例 `subscriptionsSeparator: '-'`,所有订阅将 `{subscription prefix}-{your topic name} (default to '%')`。 。 。 .
    -   `namespace`: 添加命名空间属性到 [信件属性](https://googleapis.dev/nodejs/pubsub/latest/google.pubsub.v1.html#.PubsubMessage) 当发表一个话题时.
    -   `environment`: 将环境属性添加到 [信件属性](https://googleapis.dev/nodejs/pubsub/latest/google.pubsub.v1.html#.PubsubMessage) 当发表一个话题时.

### `pubsub.listen(event, opts)`

听听具体事件.

_页:1_: 它只使用 [谷歌云订阅拉](https://cloud.google.com/pubsub/docs/pull) 现在就送货.

-   `event`:活动名称.
-   `opts`: 与听众方法有关的选项
    -   `onMessage`: 接收消息时调用的方法
    -   `onError`: 发生错误时调用的方法
    -   `options`: 与所选运输有关的选项

如果选择的运输方式是 Google Cloud PubSub, 那么 `options` 将:

-   `autoAck`: 一收到事件(默认为 `true`(中文(简体) )
-   `subscriptionOptions`: 与创建的订阅有关的选项 :
    -   `name`: 自定义订阅名称。 默认 : `event` (也与题目名称等同)
    -   `get`: 适用于 `getSubscription` 方法(请查看 [订阅选项](https://googleapis.dev/nodejs/pubsub/latest/Subscription.html#get)(中文(简体) )
    -   `sub`: 适用于订阅实例的选项(另见 [`setOptions` 方法](https://googleapis.dev/nodejs/pubsub/latest/Subscription.html#setOptions)(中文(简体) )
    -   `create`: 适用于 `createSubscription` 方法(请查看 [创建订阅选项](https://googleapis.dev/nodejs/pubsub/latest/Topic.html#createSubscription)(中文(简体) )
    -   `deadLetterTopicName`: 死信题名的订阅覆盖(见 [死信主题](https://npmcn.com/package/%40algoan/pubsub/#readme-dead-letter-topics)(中文(简体) )
-   `topicOptions`: 适用于所创建主题的选项(请查看 [专题选项](https://googleapis.dev/nodejs/pubsub/latest/Topic.html#get)(中文(简体) )
-   `topicName`:设置主题名. 默认情况下,它使用带有前缀的默认名称.

### `pubsub.emit(event, payload, opts)`

释放带有有效载荷的特定事件. 如果您在设置时添加了命名空间或环境, 它会在信件中添加属性 `PubSubFactory` 课。 也增加了一个 `_eventName` (单位:千美元) `time` 释放的属性 `payload`。 。 。 .

-   `event`:要发射的事件名称.
-   `payload`: 寄出有效载荷. 由Google缓冲,然后由Google解析 [听着](https://npmcn.com/package/%40algoan/pubsub/#readme-pubsublistenevent-options) 方法.
-   `opts`: 与 Emit 方法有关的选项
    -   `metadata`: 自定义添加到信件中的元数据
    -   `options`: 与所选运输有关的选项

如果选择的运输方式是 Google Cloud PubSub, 那么 `options` 将:

-   `topicOptions`: 适用于所创建主题的选项(请查看 [专题选项](https://googleapis.dev/nodejs/pubsub/latest/Topic.html#get)(中文(简体) )
-   `publishOptions`: 发布主题创建后设定的选项. 参见 [发布选项](https://googleapis.dev/nodejs/pubsub/latest/global.html#PublishOptions)
-   `messageOptions`: 给消息添加了额外消息选项. 参见 [信件选项](https://googleapis.dev/nodejs/pubsub/latest/google.pubsub.v1.IPubsubMessage.html)

### `pubsub.unsubscribe(event)`

停止给定订阅的服务器连接 .

-   `event`: 停止倾听的活动名称.

## 死信主题

何时 `deadLetterOptions` 设置在构建器选项中,库自动:

1.  创建死字母主题( 如果不存在)
2.  创建关于死信题的排入订阅( 防止 GCP 丢弃未发送的消息)
3.  赠款 `roles/pubsub.publisher` gCP Pub/Sub服务账户的死信题
4.  赠款 `roles/pubsub.subscriber` gCP Pub/Sub服务账户的原始订阅
5.  应用 `deadLetterPolicy` 创建的订阅

这个设定只会发生 **每新订阅一次** 重新连接到已有的订阅费用为零.

### 方式1:每个订阅的孤立的死字题(推荐给多消费者系统)

奥米 `deadLetterTopicName`。每个订阅自动获得自己的 `<subscriptionName>-deadletter` ,所以来自不同消费者的失败消息是孤立的,可以独立地重播.

```typescript
const pubsub: GCPubSub = PubSubFactory.create({
  transport: Transport.GOOGLE_PUBSUB,
  options: {
    projectId: 'my-project',
    deadLetterOptions: {
      maxDeliveryAttempts: 10, // optional, defaults to 5
    },
  },
});

// Each listen() call creates its own isolated dead-letter topic:
// - "my-orders-sub-deadletter" for the first subscription
// - "my-payments-sub-deadletter" for the second
await pubsub.listen('my-orders-sub');
await pubsub.listen('my-payments-sub');
```

### 模式2:共享的死字母主题(所有订阅的单 DLT)

提供 `deadLetterTopicName` 以将所有失败的消息传送到一个共享的话题。 全球协商进程中必须已经存在这一专题.

```typescript
const pubsub: GCPubSub = PubSubFactory.create({
  transport: Transport.GOOGLE_PUBSUB,
  options: {
    projectId: 'my-project',
    deadLetterOptions: {
      deadLetterTopicName: 'projects/my-project/topics/my-dead-letter', // fully-qualified or short name
      maxDeliveryAttempts: 5,
    },
  },
});

await pubsub.listen('my-orders-sub');   // routes to "my-dead-letter"
await pubsub.listen('my-payments-sub'); // routes to "my-dead-letter"
```

### 模式 3: 订阅覆盖

覆盖一个特定的订阅方式的死字题 `subscriptionOptions.deadLetterTopicName`。返回实例一级 `deadLetterTopicName`,然后如果两者都未设定,则自动删除.

```typescript
await pubsub.listen('my-special-sub', {
  options: {
    subscriptionOptions: {
      deadLetterTopicName: 'projects/my-project/topics/special-dead-letter',
    },
  },
});
```

### 配置排水口订阅(例如保留电文)

默认情况下,在死字题上创建的排水层订阅会使用Google Cloud默认——特别是a **7天时间** 保留信件。 提供 `drainSubscriptionOptions` 以覆盖 `CreateSubscriptionOptions` 当创建下水道订阅时使用(例如,将死字留言保存最多31天,以便有更多的时间检查和重放).

```typescript
const pubsub: GCPubSub = PubSubFactory.create({
  transport: Transport.GOOGLE_PUBSUB,
  options: {
    projectId: 'my-project',
    deadLetterOptions: {
      drainSubscriptionOptions: {
        messageRetentionDuration: { seconds: 2678400 }, // 31 days (max)
      },
    },
  },
});

await pubsub.listen('my-orders-sub');
```

和其他的死信设置一样,这只有在排水口订阅时才适用 **创建** ——已经存在的排水量认购未受影响.

### 没有死字题

若为 `deadLetterOptions` 没有设置,没有创建死信资源,也没有进行IAM呼叫——完全后向兼容.

```typescript
const pubsub: GCPubSub = PubSubFactory.create({
  transport: Transport.GOOGLE_PUBSUB,
  options: {
    projectId: 'my-project',
    // no deadLetterOptions — existing behavior unchanged
  },
});
```

## 常见问题

### @algoan/pubsub 是什么？

用于 algoan 的 PubSub 图书馆

### 如何安装 @algoan/pubsub？

在项目目录运行 npm install @algoan/pubsub，或使用 pnpm add / yarn add / bun add。

### @algoan/pubsub 支持 TypeScript 吗？

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

### @algoan/pubsub 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @algoan/pubsub 需要什么版本的 Node\.js？

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

### @algoan/pubsub 可以商用吗？

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

### @algoan/pubsub 的下载量有多少？

根据 npm 官方下载统计，@algoan/pubsub 在 2026/10/06 – 2026/11/04 这 30 天内被下载 11,799 次，日均约 393 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @algoan/pubsub 还在维护吗？

最新版本 6\.4\.3 发布于 2026/10/22（17 天前）；至今共发布 45 个版本，其中过去 12 个月发布了 5 个；首次发布于 2020/04/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。