tzdwindows 7
7badbb0d8e
- 新增浏览器模块技术文档，涵盖 BrowserCore、BrowserWindow 等核心组件 - 添加事件系统文档，包括 EventBus、GlobalEventBus 及各类事件定义 - 创建 LanguageManager 国际化管理器详细说明文档 - 新增 Log4j2OutputStream 标准输出重定向类文档 - 添加 Main 入口类启动流程与路由机制说明 - 创建 BrowserCreationCallback 回调接口使用指南 - 完善 AxisInnovatorsBox 主类架构与崩溃诊断系统文档
105 lines
4.3 KiB
Markdown
105 lines
4.3 KiB
Markdown
# 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* |