# @ethberry/nestjs-sqs 中文文档

规范地址：https://npmcn.com/package/%40ethberry/nestjs-sqs/

版本：8\.0\.0
npm 元数据更新时间：2026-11-11T19:34:53.477Z
中文译文更新时间：2026-11-13T23:31:05.517Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：126 kB，63 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：3 个
- peer 依赖：rxjs ^7\.0\.0，@nestjs/core ^11\.0\.0 \|\| ^12\.0\.0，@nestjs/common ^11\.0\.0 \|\| ^12\.0\.0，@nestjs/microservices ^11\.0\.0 \|\| ^12\.0\.0
- 首次发布：2024-09-26T08:39:20.971Z
- 最新版本发布：2026-11-11T19:34:53.253Z
- 近 30 天下载量：3555（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 4 个）

## 中文简介

测试过 [AWS 质量](https://aws.amazon.com/en/sqs/), (中文(简体) ), [弹性MQ](https://github.com/softwaremill/elasticmq),以及 [本地软件包](https://localstack.cloud/) (参见本repo中的整合测试).

## 安装

```sh
npm install @ethberry/nestjs-sqs
```

也可以使用：`pnpm add @ethberry/nestjs-sqs`、`yarn add @ethberry/nestjs-sqs`、`bun add @ethberry/nestjs-sqs`

## README

# 雀巢JS SQS

测试过 [AWS 质量](https://aws.amazon.com/en/sqs/), (中文(简体) ), [弹性MQ](https://github.com/softwaremill/elasticmq),以及 [本地软件包](https://localstack.cloud/) (参见本repo中的整合测试).

NestJS SQS是一个使SQS与NestJS一起更容易使用和控制一些需要的流量的项目. 本单元提供 基于装饰器的信件处理适合简单使用.

这个图书馆内部依赖 [bbc/sqs-生产者](https://github.com/bbc/sqs-producer) 财务报告和审定财务报表 [bbc/sqs - 消费者](https://github.com/bbc/sqs-consumer),并在 他们给予的基本功能.

默认 **`SqsSerializer`** 财务报告和审定财务报表 **`SqsDeserializer`** 用于标准队列的工作。 消息 **机构** 对 FIFO 是相同的 JSON; FIFO 元数据在 SQS 消息上, 不在 `Body`,所以只有 **序列器** fIFO 的更改: 注册 **`SqsFifoSerializer`** 通过 `serializer` 选项 `SqsClient` 编号 : `SqsServer` 需要时(全部从此包导出).

## 比起Redis和RabbitMQ运输机

巢穴的鱼 **重写** 财务报告和审定财务报表 **季度** 服务器是第一当事方:多路连接、推式交付和经纪人记录上丰富的元数据. **质量** 设计不同:

| 专题 | Redis / RMQ( 典型) | 这个SQS运输 |
| --- | --- | --- |
| 交付 | 经常推动/订阅 | **投票时间长** (单位:千美元)`sqs-consumer`(中文(简体) ) |
| 语义 | 取决于经纪人 | **至少从头到尾**; 可能复制 |
| 请求复制 | 频道/回复 | **两个队列** + 关联 **`id`** 在JSON体内 |
| 订购 | 特定经纪人 | **标准** = 成绩最佳; **FIFO 飞行器** =每个信息组(见AWS文件) |
| 元数据 | 页眉/ 属性 | **`Body`** 默认保存 Nest 数据包; 使用 **`SqsContext`** 用于生 `Message` (属性,收讫柄等) |

巢穴 **API 密码** 保持熟悉: `@MessagePattern` 编号 : `@EventPattern`, (中文(简体) ), `ClientProxy`和序列器——但是 **操作行为** 遵循 SQS(可见超时, DLQ, 减速). 计划相应重审并具"一能".

## 所需资源

-   **节点.js 24+** (将运行于22日,但不测试)

## 安装

```shell
$ npm i --save @ethberry/nestjs-sqs
```

## 当地融合测试

已读集成规格 **`ELASTICMQ_URL`** 财务报告和审定财务报表 **`LOCALSTACK_URL`** 从a **`.env`** 文件位于 repo 根(承诺默认值)。 启动弹性MQ和本地Stack,然后进行测试:

```shell
$ npm i
$ npm run docker:sqs:up
$ npm test
$ npm run docker:sqs:down
```

通过编辑覆盖终点 `.env` (例如不同的端口).

要匹配CI( lint + 测试) 在依赖度和多克值上升之后:

```shell
$ npm run lint && npm test
```

## 快速启动

### 海关运输登记

就像你登记其他微服务一样

```ts
import { SQSClient } from "@aws-sdk/client-sqs";
import { SqsServer } from "@ethberry/nestjs-sqs";

const sqs = new SQSClient({
  endpoint: "http://localhost:9324",
  region: "none",
  credentials: {
    accessKeyId: "x",
    secretAccessKey: "x",
  },
});

app.connectMicroservice({
  strategy: new SqsServer({
    consumerOptions: {
      sqs,
      queueUrl: "http://localhost:9324/queue/producer",
    },
    producerOptions: {
      sqs,
      queueUrl: "http://localhost:9324/queue/consumer",
    },
  }),
});
```

### 装饰方法

您需要在您的 NestJS 控制器中解析方法, 以便它们作为事件处理器自动附加 用于接收 SQS 信件 :

```ts
@Controller()
export class SqsController {
  @MessagePattern(MESSAGE_TYPE)
  public handleMessage(message: any): Promise<any> {
    // do something, return result
  }

  @EventPattern(EVENT_TYPE)
  public handleEvent(event: any): Promise<void> {
    // do something
  }
}
```

### 处理器上下文`SqsContext`(中文(简体) )

喜欢 **`RmqContext`** 或者说 **`RedisContext`**时,您可以注射 **`SqsContext`** 与 `@Ctx()` 读取原始 AWS **`Message`**消费者 **队列 URL**,则 **模式** 绳子。 第一个论点仍然是被破坏 **有效载数** (单位:千美元)`data` 从身体上).

```ts
import { Controller } from "@nestjs/common";
import { Ctx, MessagePattern, Payload } from "@nestjs/microservices";
import { SqsContext } from "@ethberry/nestjs-sqs";

@Controller()
export class SqsController {
  @MessagePattern(MESSAGE_TYPE)
  public handleRpc(@Payload() data: unknown, @Ctx() ctx: SqsContext): Promise<unknown> {
    const sqs = ctx.getMessage();
    const attrs = sqs.MessageAttributes;
    // ...
    return { ok: true };
  }
}
```

无顶层排放的事件 **`id`** 在数据包中以 **`@EventPattern`** (想法和其他巢穴运输一样).

### 伟大的关闭

[`sqs-consumer`](https://github.com/bbc/sqs-consumer) 可以等待最后的民调和飞行 **`handleMessage`** 停止前工作。 设定 **`pollingCompleteWaitTimeMs`** 打开 **`consumerOptions`** (毫秒,你愿意等待) . **`SqsServer.close()`** 转发可选 **`StopOptions`** 改为 **`consumer.stop()`** (例如 `{ abort: true }` (b) 取消飞行中的民意调查——节制使用).

```ts
new SqsServer({
  consumerOptions: {
    sqs,
    queueUrl: "...",
    pollingCompleteWaitTimeMs: 10_000,
  },
  producerOptions: { sqs, queueUrl: "..." },
});
```

当应用停止,打电话 **`app.close()`** (或以其他方式援引微服务) **`close`**)所以消费者关闭.

### 产生信件

```ts
import { SQSClient } from "@aws-sdk/client-sqs";
import { SqsClient, SQS_SERVICE } from "@ethberry/nestjs-sqs";

const sqs = new SQSClient({
  endpoint: "http://localhost:9324",
  region: "none",
  credentials: {
    accessKeyId: "x",
    secretAccessKey: "x",
  },
});

@Module({
  imports: [
    ClientsModule.register([
      {
        name: SQS_SERVICE,
        customClass: SqsClient,
        options: {
          consumerUrl: "http://localhost:9324/queue/consumer",
          producerUrl: "http://localhost:9324/queue/producer",
          sqs,
        },
      },
    ]),
  ],
  providers: [AppService],
})
class AppModule {}

export class AppService {
  constructor(
    @Inject(SQS_SERVICE)
    private readonly sqsClientProxy: ClientProxy,
  ) {}

  public dispatch(): Promise<void> {
    void this.sqsClientProxy.emit(EVENT_NAME, {});
  }
}
```

## 许可证

这个项目根据麻省理工学院许可证的规定获得许可.

## 常见问题

### @ethberry/nestjs-sqs 是什么？

测试过 AWS 质量, \(中文\(简体\) \), 弹性MQ,以及 本地软件包 \(参见本repo中的整合测试\)\.

### 如何安装 @ethberry/nestjs-sqs？

在项目目录运行 npm install @ethberry/nestjs-sqs，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（^7\.0\.0）、@nestjs/core（^11\.0\.0 \|\| ^12\.0\.0）、@nestjs/common（^11\.0\.0 \|\| ^12\.0\.0）、@nestjs/microservices（^11\.0\.0 \|\| ^12\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ethberry/nestjs-sqs 支持 TypeScript 吗？

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

### @ethberry/nestjs-sqs 支持 ESM 还是 CommonJS？

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

### @ethberry/nestjs-sqs 需要什么版本的 Node\.js？

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

### @ethberry/nestjs-sqs 可以商用吗？

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

### @ethberry/nestjs-sqs 的下载量有多少？

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

### @ethberry/nestjs-sqs 还在维护吗？

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