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

### 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. 使用代码示例

### 定义事件
```java
public class UserLoginEvent {
    public final String username;
    public UserLoginEvent(String name) { this.username = name; }
}
```

### 注册监听器
```java
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);
```

### 发布事件
```java
bus.post(new UserLoginEvent("Admin"));
```

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