window-axis-innovators-box1.17/api-documentation/events/EventBus.md

EventBus 类技术文档

包路径: com.axis.innovators.box.events.EventBus
主要功能: 发布-订阅（Publish-Subscribe）模式的事件中心
作者: tzdwindows 7

---

1. 概述

EventBus 是 Axis Innovators Box 框架的核心通信组件。它通过事件驱动的方式实现模块间的解耦，允许应用程序的不同部分在无需相互引用的情况下进行信息交换。

该实现采用了 基于注解（Annotation-based） 的方法，通过反射动态扫描和分发事件。它不仅支持简单的事件发布，还具备完整的对象生命周期管理（注册/注销）以及跨类层级的事件监听能力。

2. 核心架构设计

2.1 存储机制

EventBus 内部维护了两个关键的映射表，以保证高效的事件分发和快速的资源清理：

1. eventSubscribers (Map<Class, List>):
   • 用途: 用于事件发布。
   • 逻辑: 以事件的 Class 类型为键，快速找到所有订阅了该事件的监听者列表。
2. targetSubscribers (Map<Object, List>):
   • 用途: 用于对象注销。
   • 逻辑: 以订阅对象实例为键，记录该对象注册的所有监听器，确保在对象销毁时能一次性清理所有相关引用，防止内存泄漏。

2.2 订阅者封装 (Subscriber)

内部类 Subscriber 封装了执行事件回调所需的三个要素：

• Target: 接收事件的对象实例。
• Method: 标记了 @SubscribeEvent 的方法对象。
• EventType: 该监听器关注的事件类型（方法参数类型）。

---

3. 关键功能详解

3.1 动态注册 (register)

当一个对象调用 register 时，EventBus 会：

1. 递归扫描: 遍历目标对象的所有方法，包括从父类继承的方法（通过 getSuperclass() 向上递归）。
2. 注解验证: 筛选出带有 @SubscribeEvent 注解的方法。
3. 参数检查: 确保方法有且仅有一个参数（该参数即为监听的事件类型）。
4. 建立索引: 将符合条件的方法封装成 Subscriber 并存入上述两个映射表中。

3.2 事件发布 (post)

当发布一个事件对象时：

1. 类型匹配: 获取事件的 Class 类型。
2. 副本保护: 在遍历订阅者列表前创建 copySubs 副本。这是为了防止在执行事件回调过程中，某个监听者尝试注销自己而引发 ConcurrentModificationException。
3. 反射调用: 通过 setAccessible(true) 强制调用（即使是私有方法），并将事件对象传入。

3.3 生命周期管理

• 注销 (unregister): 彻底切断事件总线对目标对象的引用，是资源清理的关键步骤。
• 熔断 (shutdown): 一旦总线关闭，所有的 post 操作将失效，确保在应用关闭阶段不再产生新的业务逻辑执行。

---

4. API 接口说明

方法	描述
void register(Object target)	扫描目标对象并注册所有合法的事件监听器。
void unregister(Object target)	移除该对象在总线上的所有订阅关系。
boolean post(Object event)	向所有订阅了该事件类型的监听者发送事件。
void shutdown()	关闭事件总线。

---

5. 技术亮点

• 继承支持: 通过 while (clazz != null) 循环，支持在父类中定义通用的事件处理逻辑，子类只需注册即可继承该能力。
• 解耦性: 发布者完全不知道谁在处理事件，监听者也无需知道事件由谁产生，只需关注事件本身。
• 健壮性: 内置 handleException 机制，确保某个监听器执行失败时不会影响总线上其他监听器的正常运行。

---

6. 使用代码示例

定义事件

public class UserLoginEvent {
    public final String username;
    public UserLoginEvent(String name) { this.username = name; }
}

注册监听器

public class LogModule {
    @SubscribeEvent
    public void onUserLogin(UserLoginEvent event) {
        System.out.println("用户登录: " + event.username);
    }
}

// 在初始化处
EventBus bus = new EventBus();
LogModule logModule = new LogModule();
bus.register(logModule);

发布事件

bus.post(new UserLoginEvent("Admin"));

---

文档生成时间: 2026-01-02