# @geekmidas/events 中文文档

规范地址：https://npmcn.com/package/%40geekmidas/events/

版本：9\.6\.1
npm 元数据更新时间：2026-11-16T09:29:27.422Z
中文译文更新时间：2026-11-16T09:32:12.052Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：489 kB，297 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：amqplib ^0\.10\.3，pg-boss \>=12\.0\.0，@geekmidas/schema ^9\.6\.1，@aws-sdk/client-sns ~3\.908\.0，@aws-sdk/client-sqs ~3\.908\.0
- 首次发布：2025-10-19T18:21:42.531Z
- 最新版本发布：2026-11-16T09:29:27.105Z
- 近 30 天下载量：14660（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：205（近 12 个月 203 个）

## 中文简介

一个支持多个后端(Basic,RabbitMQ,SQS,SNS)的统一事件消息库. 写入事件驱动的代码一次,并在消息系统之间切换,而不改变应用程序逻辑.

## 安装

```sh
npm install @geekmidas/events
```

也可以使用：`pnpm add @geekmidas/events`、`yarn add @geekmidas/events`、`bun add @geekmidas/events`

## README

# @geekmidas/活动

一个支持多个后端(Basic,RabbitMQ,SQS,SNS)的统一事件消息库. 写入事件驱动的代码一次,并在消息系统之间切换,而不改变应用程序逻辑.

## 特征

-   ✅ **统一接口**: 单一API,用于发布和订阅不同消息系统中的事件
-   ✅ **类型安全**: 信息类型和有效载荷的完整类型脚本支持和类型推论
-   ✅ **多个后端**: 基本(记忆中),兔MQ,AWS SQS,AWS SNS
-   ✅ **连接字符串**: 使用简单的连接字符串配置消息系统
-   ✅ **工厂模式**: 从连接或连接字符串创建出版商和订阅者
-   ✅ **安全理事会 一体化**: 以自动排队设置管理以推为主的邮件
-   ✅ **弹性**: 直接 SQS 访问或管理 SNS 订阅模式

## 安装

```bash
pnpm add @geekmidas/events
```

### 同伴依赖关系

根据您使用的通讯后端, 安装相应的 SDK :

```bash
# For RabbitMQ
pnpm add amqplib

# For AWS SQS/SNS
pnpm add @aws-sdk/client-sqs @aws-sdk/client-sns
```

## 快速启动

### 1\. 定义您的信件类型

```typescript
import type { PublishableMessage } from '@geekmidas/events';

type UserEvents =
  | PublishableMessage<'user.created', { userId: string; email: string }>
  | PublishableMessage<'user.updated', { userId: string; changes: Record<string, any> }>
  | PublishableMessage<'user.deleted', { userId: string }>;
```

### 2\. 创建出版商和订阅商

```typescript
import { Publisher, Subscriber } from '@geekmidas/events';

// Create publisher from connection string
const publisher = await Publisher.fromConnectionString<UserEvents>(
  'rabbitmq://localhost:5672?exchange=events'
);

// Create subscriber from connection string
const subscriber = await Subscriber.fromConnectionString<UserEvents>(
  'rabbitmq://localhost:5672?exchange=events&queue=user-service'
);

// Subscribe to events
await subscriber.subscribe(['user.created', 'user.updated'], async (message) => {
  console.log('Received:', message.type, message.payload);
});

// Publish events
await publisher.publish([
  {
    type: 'user.created',
    payload: { userId: '123', email: 'user@example.com' }
  }
]);
```

## 通讯后端

### 基础(记忆)

适合测试和开发 使用Node.js EventEmitter(英语:Node.js EventEmitter).

```typescript
import { BasicConnection, BasicPublisher, BasicSubscriber } from '@geekmidas/events/basic';

const connection = new BasicConnection();
await connection.connect();

const publisher = new BasicPublisher(connection);
const subscriber = new BasicSubscriber(connection);

await subscriber.subscribe(['user.created'], async (message) => {
  console.log('User created:', message.payload);
});

await publisher.publish([
  { type: 'user.created', payload: { userId: '123' } }
]);
```

**连接字符串格式 :**

```
basic://
```

### 兔子MQ

具有先进特性的制作准备信息经纪人.

```typescript
import { RabbitMQConnection, RabbitMQPublisher, RabbitMQSubscriber } from '@geekmidas/events/rabbitmq';

const connection = new RabbitMQConnection({
  url: 'amqp://localhost:5672',
  exchange: 'events',
  exchangeType: 'topic',
});
await connection.connect();

const publisher = new RabbitMQPublisher(connection);
const subscriber = new RabbitMQSubscriber(connection, {
  queueName: 'user-service',
  prefetch: 10,
});

await subscriber.subscribe(['user.created', 'user.updated'], async (message) => {
  console.log('Processing:', message.type, message.payload);
});

await publisher.publish([
  { type: 'user.created', payload: { userId: '123' } }
]);
```

**连接字符串格式 :**

```
rabbitmq://localhost:5672?exchange=events&exchangeType=topic&queue=myqueue
```

**选项 :**

-   `exchange` - 交换名称(需要)
-   `exchangeType` - 交换类型: `topic`, (中文(简体) ), `fanout`, (中文(简体) ), `direct` (默认 : `topic`(中文(简体) )
-   `queue` - 队列名称(可选,如果不提供则自动生成)
-   `prefetch` - 前置限制( 默认: 10)

### AWS 质量

直接 SQS 队列访问以获取基于拉动的信件 .

```typescript
import { SQSConnection, SQSPublisher, SQSSubscriber } from '@geekmidas/events/sqs';

const connection = new SQSConnection({
  queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/my-queue',
  region: 'us-east-1',
});
await connection.connect();

const publisher = new SQSPublisher(connection);
const subscriber = new SQSSubscriber(connection, {
  waitTimeSeconds: 20, // Long polling
  maxMessages: 10,
});

await subscriber.subscribe(['user.created'], async (message) => {
  console.log('Received from SQS:', message.payload);
});

await publisher.publish([
  { type: 'user.created', payload: { userId: '123' } }
]);
```

**连接字符串格式 :**

```
sqs://?queueUrl=https://sqs.us-east-1.amazonaws.com/123456789/my-queue&region=us-east-1
```

**选项 :**

-   `queueUrl` - SQS队列 URL( 需要)
-   `region` - AWS区域(需要)
-   `endpoint` - 自定义本地端点( 可选)
-   `accessKeyId`, (中文(简体) ), `secretAccessKey` - AWS证书(可选)
-   `waitTimeSeconds` - 投票时间长(默认:20)
-   `maxMessages` - 每次民意调查的最大消息(默认:10)

### AWS 系统

基于 Push 的 pub/ sub 消息,带有自动 SQS 队列管理功能.

```typescript
import { SNSConnection, SNSPublisher, SNSSubscriber } from '@geekmidas/events/sns';

const connection = new SNSConnection({
  topicArn: 'arn:aws:sns:us-east-1:123456789:events',
  region: 'us-east-1',
});
await connection.connect();

const publisher = new SNSPublisher(connection);

// SNS Subscriber automatically creates and manages an SQS queue
const subscriber = new SNSSubscriber(connection, {
  queueName: 'my-service-queue', // Optional
  createQueue: true,
  deleteQueueOnClose: false,
});

await subscriber.subscribe(['user.created'], async (message) => {
  console.log('Received via SNS:', message.payload);
});

await publisher.publish([
  { type: 'user.created', payload: { userId: '123' } }
]);

// Cleanup
await subscriber.stop(); // Unsubscribes and optionally deletes queue
```

**连接字符串格式 :**

```
sns://?topicArn=arn:aws:sns:us-east-1:123456789:events&region=us-east-1&queueName=my-queue
```

**选项 :**

-   `topicArn` - SNS主题ARN(需要)
-   `region` - AWS区域(需要)
-   `endpoint` - 自定义本地端点( 可选)
-   `queueName` - SQS 队列名称( 如果不提供, 可选择, 自动生成)
-   `createQueue` - 自动创建队列( 默认: 真)
-   `deleteQueueOnClose` - 删除站点上的队列( 默认: 对自动生成队列的真)

## 高级使用

### 管理SNS-SQS 通过 SQS 连接字符串订阅

您可以使用 SQS 连接字符串与 a `topicArn` 自动获得管理 SNS 订阅的参数 :

```typescript
import { Subscriber } from '@geekmidas/events';

// This automatically creates an SNS subscriber with managed queue
const subscriber = await Subscriber.fromConnectionString(
  'sqs://?topicArn=arn:aws:sns:us-east-1:123456789:events&queueName=my-queue&region=us-east-1'
);
```

何时 `topicArn` 它自动存在于 SQS 连接字符串中 :

1.  创建 SNS 连接
2.  设置管理的 SQS 队列
3.  订阅队列到 SNS 主题
4.  按主题 ARN 和消息类型过滤信件

### SNS-SQS手册 一体化

要进行更多的控制, 手动订阅 SQS 队列到 SNS 主题 :

```typescript
import { SNSPublisher, SNSConnection } from '@geekmidas/events/sns';
import { SQSSubscriber, SQSConnection } from '@geekmidas/events/sqs';

// Publisher sends to SNS
const snsConnection = new SNSConnection({
  topicArn: 'arn:aws:sns:us-east-1:123456789:events',
  region: 'us-east-1',
});
const publisher = new SNSPublisher(snsConnection);

// Subscriber receives from SQS (queue must be subscribed to SNS topic)
const sqsConnection = new SQSConnection({
  queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/my-queue',
  region: 'us-east-1',
});
const subscriber = new SQSSubscriber(sqsConnection, {
  expectedTopicArn: 'arn:aws:sns:us-east-1:123456789:events', // Verify messages
});

await subscriber.subscribe(['user.created'], async (message) => {
  // Automatically parses SNS wrapper
  console.log('Received:', message.payload);
});
```

### 共享连接

您可以在出版社和订阅者之间共享连接 :

```typescript
import { EventConnectionFactory, Publisher, Subscriber } from '@geekmidas/events';

const connection = await EventConnectionFactory.create(
  'rabbitmq://localhost:5672?exchange=events'
);

const publisher = await Publisher.fromConnection(connection);
const subscriber = await Subscriber.fromConnection(connection);
```

### 信件过滤

订阅者只收到他们订阅的信息:

```typescript
// Only receives user.created and user.updated
await subscriber.subscribe(['user.created', 'user.updated'], async (message) => {
  if (message.type === 'user.created') {
    console.log('New user:', message.payload.userId);
  } else {
    console.log('User updated:', message.payload.userId);
  }
});
```

### 处理错误

```typescript
await subscriber.subscribe(['user.created'], async (message) => {
  try {
    await processUser(message.payload);
  } catch (error) {
    console.error('Failed to process user:', error);
    // For RabbitMQ: message will be nack'd and requeued
    // For SQS: message visibility timeout will expire and retry
    throw error;
  }
});
```

## 结构模式

### Fan-Out (SNS ~ 多个 SQS 队列)

```
                    ┌─────────────┐
                    │ SNS Topic   │
                    └──────┬──────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
       ┌────▼────┐    ┌───▼─────┐   ┌───▼─────┐
       │ Queue 1 │    │ Queue 2 │   │ Queue 3 │
       └────┬────┘    └────┬────┘   └────┬────┘
            │              │              │
       ┌────▼────┐    ┌───▼─────┐   ┌───▼─────┐
       │Service 1│    │Service 2│   │Service 3│
       └─────────┘    └─────────┘   └─────────┘
```

### 直接队列( SQS)

```
┌───────────┐      ┌────────────┐      ┌──────────┐
│ Publisher │─────▶│  SQS Queue │─────▶│Subscriber│
└───────────┘      └────────────┘      └──────────┘
```

### 管理订阅(SNS订阅者)

```
┌───────────┐      ┌───────────┐      ┌─────────────┐      ┌──────────┐
│ Publisher │─────▶│ SNS Topic │─────▶│ SQS Queue   │─────▶│Subscriber│
└───────────┘      └───────────┘      │(auto-managed)│      └──────────┘
                                       └─────────────┘
```

## 测试

使用基本执行进行测试:

```typescript
import { BasicConnection, BasicPublisher, BasicSubscriber } from '@geekmidas/events/basic';
import { describe, it, expect } from 'vitest';

describe('Event processing', () => {
  it('should process user events', async () => {
    const connection = new BasicConnection();
    const publisher = new BasicPublisher(connection);
    const subscriber = new BasicSubscriber(connection);

    const received = [];
    await subscriber.subscribe(['user.created'], async (message) => {
      received.push(message);
    });

    await publisher.publish([
      { type: 'user.created', payload: { userId: '123' } }
    ]);

    expect(received).toHaveLength(1);
    expect(received[0].payload.userId).toBe('123');
  });
});
```

## 本地软件包设置

对于带有SQS/SNS的本地开发,请使用localStack:

```yaml
# docker-compose.yml
services:
  localstack:
    image: localstack/localstack:latest
    ports:
      - "4566:4566"
    environment:
      - SERVICES=sqs,sns
      - DEBUG=1
```

然后使用 `endpoint: 'http://localhost:4566'` 在您的配置中.

## API 参考

### 出版商

```typescript
class Publisher {
  static fromConnectionString<T>(connectionStr: string): Promise<EventPublisher<T>>
  static fromConnection<T>(connection: EventConnection): Promise<EventPublisher<T>>
}
```

### 订阅者

```typescript
class Subscriber {
  static fromConnectionString<T>(connectionStr: string): Promise<EventSubscriber<T>>
  static fromConnection<T>(connection: EventConnection): Promise<EventSubscriber<T>>
}
```

### 事件工具

```typescript
interface EventPublisher<TMessage> {
  publish(messages: TMessage[]): Promise<void>
}
```

### 事件订阅者

```typescript
interface EventSubscriber<TMessage> {
  subscribe(
    messages: TMessage['type'][],
    listener: (payload: TMessage) => Promise<void>
  ): Promise<void>
  stop(): void | Promise<void>
}
```

### 可出版新闻

```typescript
type PublishableMessage<TType extends string, TPayload> = {
  type: TType
  payload: TPayload
}
```

## 最佳做法

1.  **定义信件类型**: 对所有信件类型使用类型脚本联盟类型
2.  **信件类型命名**: 对命名间隔使用点标记(例如, `user.created`, (中文(简体) ), `order.shipped`(中文(简体) )
3.  **处理错误**: 总是处理信件收听器中的错误
4.  **连接集合**: 在可能的情况下重新使用连接
5.  **测试**: 单位测试使用基本实施,整合测试使用真正的后端
6.  **清理**: 总是呼叫 `stop()` 关闭时的订阅者
7.  **信件版本**: 将版本包含在消息类型中,用于断开更改(例如, `user.created.v2`(中文(简体) )

## 许可证

麻省理工学院

## 常见问题

### @geekmidas/events 是什么？

一个支持多个后端\(Basic,RabbitMQ,SQS,SNS\)的统一事件消息库\. 写入事件驱动的代码一次,并在消息系统之间切换,而不改变应用程序逻辑\.

### 如何安装 @geekmidas/events？

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

### @geekmidas/events 支持 TypeScript 吗？

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

### @geekmidas/events 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @geekmidas/events 可以商用吗？

@geekmidas/events 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @geekmidas/events 的下载量有多少？

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

### @geekmidas/events 还在维护吗？

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

