@geekmidas/events

中文文档
9.6.1发布于 2026/11/16TypeScriptESM + CJS构建来源已验证近 30 天下载 1.5万

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

中文使用文档
文档目录31 节
  1. 特征
  2. 安装
  3. 同伴依赖关系
  4. 快速启动
  5. 1. 定义您的信件类型
  6. 2. 创建出版商和订阅商
  7. 通讯后端
  8. 基础(记忆)
  9. 兔子MQ
  10. AWS 质量
  11. AWS 系统
  12. 高级使用
  13. 管理SNS-SQS 通过 SQS 连接字符串订阅
  14. SNS-SQS手册 一体化
  15. 共享连接
  16. 信件过滤
  17. 处理错误
  18. 结构模式
  19. Fan-Out (SNS ~ 多个 SQS 队列)
  20. 直接队列( SQS)
  21. 管理订阅(SNS订阅者)
  22. 测试
  23. 本地软件包设置
  24. API 参考
  25. 出版商
  26. 订阅者
  27. 事件工具
  28. 事件订阅者
  29. 可出版新闻
  30. 最佳做法
  31. 许可证

@geekmidas/活动

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

特征

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

安装

pnpm add @geekmidas/events

同伴依赖关系

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

# For RabbitMQ
pnpm add amqplib

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

快速启动

1. 定义您的信件类型

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. 创建出版商和订阅商

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: '[email protected]' }
  }
]);

通讯后端

基础(记忆)

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

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

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

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 队列访问以获取基于拉动的信件 .

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 队列管理功能.

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 订阅的参数 :

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 主题 :

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);
});

共享连接

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

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

信件过滤

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

// 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);
  }
});

处理错误

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)│      └──────────┘
                                       └─────────────┘

测试

使用基本执行进行测试:

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:

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

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

API 参考

出版商

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

订阅者

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

事件工具

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

事件订阅者

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

可出版新闻

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 共发布 205 个版本,首次发布于 2025/10/20;过去 12 个月发布了 203 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
9.6.1latest2026/11/16今天
10.0.0-alpha.185alpha2026/11/16今天
10.0.0-alpha.1842026/11/16今天
10.0.0-alpha.1832026/11/16今天
10.0.0-alpha.1822026/11/132 天前
10.0.0-alpha.1812026/11/133 天前

关于 @geekmidas/events 的常见问题

@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 和提交记录判断。