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 —— 让业务模块之间像发微信一样简单沟通，告别"你找我、我找它"的混乱局面！✨