👁 Image
TJC.Cyclops.EventBus 2026.6.11.2

Cyclops.EventBus

📢 Cyclops世界的"快递中转站" 📢

想象一下，你的应用程序就像一个繁忙的写字楼：订单模块创建了订单，需要通知库存模块扣减库存、通知邮件模块发送确认邮件、通知日志模块记录操作...如果每个模块都要直接找对方"喊话"，系统很快就会变成一团乱麻。

Cyclops.EventBus 就是这座写字楼的"智能快递系统"——谁有事要通知，只需把"包裹"（事件）扔进快递站，快递员会自动把包裹送到所有关心这件事的人手中。发送者不用知道谁在接收，接收者不用知道谁发送的，大家各忙各的，互不干扰。

🌟 它能做什么

• 解耦通信：模块 A 发布事件，模块 B/C/D 各自处理，彼此不需要直接认识
• 异步处理：事件自动排队，不阻塞主业务流程（就像外卖订单丢进系统后，厨师慢慢做，顾客不用站着等）
• 灵活订阅：可以永久关注某类事件，也可以"只听一次"
• 错误兜底：处理失败时不崩系统，还能自定义错误恢复逻辑
• 开箱即用：基于 .NET 原生的 Channels 实现，高性能、低依赖

🏗️ 快递站的内部构造

Cyclops.Common/EventBus/ # "快递单模板"（接口定义）
├── IEventBus.cs # 快递站门面：发件、订阅、退订
├── IEventData.cs # 包裹标签：事件名称、发生时间、来源
├── IEventHandler.cs # 收件人签名：怎么处理包裹、处理失败怎么办
└── IEventChannel.cs # 传送带：把包裹从发货口运到收货口

Cyclops.EventBus/ # "快递站实体建筑"
├── Core/
│ ├── EventBus.cs # 快递总站：调度一切
│ ├── EventChannel.cs # 自动传送带：基于 Channel 的高效传输
│ ├── EventPersistence.cs # 备份仓库：可选的事件存档
│ └── SubscriptionInfo.cs # 订阅登记簿：谁关心什么事件
├── Models/
│ ├── BaseEventData.cs # 标准包裹箱：事件数据的默认实现
│ └── EventBusOptions.cs # 站点配置：队列容量、是否存档等
└── Extensions/
 └── EventBusServiceExtensions.cs # 开业指南：DI 注册扩展方法

🚀 五分钟上手

第一步：注册快递站（Startup 配置）

using Cyclops.EventBus.Extensions;

// 在 ConfigureServices 中
services.AddEventBus(options =>
{
 options.MaxQueueCapacity = 10000; // 传送带最多堆多少包裹
 options.EnablePersistence = true; // 要不要留个底单存档
});

// 注册你的"收件人"
services.AddEventHandler<OrderCreatedEvent, OrderCreatedEventHandler>();

// 或者一键扫描整个程序集，自动注册所有收件人
services.AddEventHandlers();

第二步：定义你的"包裹"（事件）

using Cyclops.EventBus.Models;

// 订单创建事件——这就是你的包裹箱
public class OrderCreatedEvent : BaseEventData
{
 public long OrderId { get; set; }
 public string CustomerName { get; set; }
 public decimal TotalAmount { get; set; }

 public OrderCreatedEvent() : base("OrderCreated") { }
}

第三步：写个"收件人"（事件处理器）

using Cyclops.Common.EventBus;

public class OrderCreatedEventHandler : IEventHandler<OrderCreatedEvent>
{
 private readonly IEmailService _emailService;
 private readonly IInventoryService _inventoryService;

 public OrderCreatedEventHandler(IEmailService emailService, IInventoryService inventoryService)
 {
 _emailService = emailService;
 _inventoryService = inventoryService;
 }

 public async Task HandleAsync(OrderCreatedEvent eventData)
 {
 // 收到包裹后，发邮件通知客户
 await _emailService.SendOrderConfirmationAsync(eventData.CustomerName, eventData.OrderId);

 // 通知仓库扣减库存
 await _inventoryService.DeductStockAsync(eventData.OrderId);
 }

 public async Task OnErrorAsync(Exception ex)
 {
 // 如果处理包裹时出了岔子，比如邮件服务器挂了
 // 这里可以记录日志、发送告警，甚至把包裹转交给人工处理
 Console.WriteLine($"处理订单 {eventData?.OrderId} 时出错了：{ex.Message}");
 }
}

第四步：扔"包裹"进快递站（发布事件）

using Cyclops.Common.EventBus;

public class OrderService
{
 private readonly IEventBus _eventBus;

 public OrderService(IEventBus eventBus)
 {
 _eventBus = eventBus;
 }

 public async Task CreateOrderAsync(string customerName, decimal amount)
 {
 // 1. 把订单存进数据库（主业务逻辑）
 var orderId = await SaveOrderToDatabaseAsync(customerName, amount);

 // 2. 把"订单已创建"的消息丢进快递站
 // 这一步不会阻塞，马上返回，邮件和库存处理在后台慢慢跑
 await _eventBus.PublishAsync(new OrderCreatedEvent
 {
 OrderId = orderId,
 CustomerName = customerName,
 TotalAmount = amount
 });
 }
}

🔧 高级玩法

只想听一次的事件（一次性订阅）

// 系统启动时只想执行一次的初始化任务
_eventBus.SubscribeOnce<SystemStartupEvent, SystemInitHandler>();

查询有多少人关心某类事件

int subscriberCount = _eventBus.GetSubscriberCount<OrderCreatedEvent>();
Console.WriteLine($"有 {subscriberCount} 个模块在关注订单创建事件");

取消关注

// 某个模块下线了，不再接收这类事件
_eventBus.Unsubscribe<OrderCreatedEvent>();

⚙️ 站点配置说明

public class EventBusOptions
{
 /// 传送带最大容量，默认能堆 10000 个包裹
 /// 超过这个数新包裹会排队等待（不会丢失）
 public int MaxQueueCapacity { get; set; } = 10000;

 /// 是否开启存档，默认开启
 /// 开启后每个事件都会留个底单，方便事后查账
 public bool EnablePersistence { get; set; } = true;

 /// 轮询间隔（毫秒），默认 100ms
 /// 传送带多久去"仓库"看一次有没有新包裹
 public int Sensitivities { get; set; } = 100;

 /// 最大并发处理数，默认 4
 /// 同时能有几个人在拆包裹
 public int MaxDegreeOfParallelism { get; set; } = 4;
}

💡 什么时候用 EventBus

📝 最佳实践

1. 事件命名用过去时：OrderCreated（订单已创建）、PaymentReceived（款项已收到），表示"已经发生了的事实"
2. 事件数据要自包含：包裹里要有足够信息让收件人干活，但不要把整个数据库塞进去
3. 处理器要轻量：如果一个处理器里做了 10 件事，考虑拆成 10 个处理器，各处理各的
4. 错误处理别偷懒：实现 OnErrorAsync，至少把错误记下来，不然出了问题找不到原因

🤝 贡献

欢迎提交 Issue 或 Pull Request！

📄 许可证

MIT License

Cyclops.EventBus —— 让业务模块之间像发微信一样简单沟通，告别"你找我、我找它"的混乱局面！✨