@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®ion=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®ion=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®ion=us-east-1'
);
何时 topicArn 它自动存在于 SQS 连接字符串中 :
- 创建 SNS 连接
- 设置管理的 SQS 队列
- 订阅队列到 SNS 主题
- 按主题 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
}
最佳做法
- 定义信件类型: 对所有信件类型使用类型脚本联盟类型
- 信件类型命名: 对命名间隔使用点标记(例如,
user.created, (中文(简体) ),order.shipped(中文(简体) ) - 处理错误: 总是处理信件收听器中的错误
- 连接集合: 在可能的情况下重新使用连接
- 测试: 单位测试使用基本实施,整合测试使用真正的后端
- 清理: 总是呼叫
stop()关闭时的订阅者 - 信件版本: 将版本包含在消息类型中,用于断开更改(例如,
user.created.v2(中文(简体) )
许可证
麻省理工学院