# GlobalEventBus 类技术文档

**包路径:** `com.axis.innovators.box.events.GlobalEventBus`  
**主要功能:** 全局单例事件总线访问点  
**作者:** tzdwindows 7

---

## 1. 概述

`GlobalEventBus` 是 **Axis Innovators Box** 框架中 `EventBus` 机制的静态包装类。它的核心作用是提供一个**全局唯一的、线程安全**的事件分发中心。

在一个复杂的解耦系统中，虽然可以实例化多个 `EventBus`（用于局部通信），但通常需要一个贯穿整个应用程序生命周期的主总线。`GlobalEventBus` 通过预定义的静态实例，消除了在不同模块、控制器或类之间传递 `EventBus` 引用的复杂性，实现了真正的“随处注册，随处发布”。

## 2. 核心架构设计

### 2.1 单例模式 (Singleton)
该类采用了最简洁的静态常量初始化方式：
```java
public static final EventBus EVENT_BUS = new EventBus();
```
*   **线程安全性**: 依赖于 Java 类加载机制，保证了 `EVENT_BUS` 实例在全局范围内的唯一性且只会被初始化一次。
*   **可见性**: `public` 修饰符允许框架内任何位置的代码直接访问，无需通过复杂的依赖注入（DI）容器。

### 2.2 职责定位
`GlobalEventBus` 本身不包含复杂的逻辑，它更像是一个“门户”：
1.  **持有者**: 持有 `EventBus` 的核心实例。
2.  **默认中心**: 作为系统默认的、最高层级的通信渠道。

---

## 3. 关键特性

*   **零配置访问**: 开发者无需关心 `EventBus` 的初始化时机，直接通过 `GlobalEventBus.EVENT_BUS` 即可获取能力。
*   **一致性**: 确保了核心系统事件（如应用启动、配置变更、全局错误处理）都在同一个频道内流动。
*   **低耦合**: 模块 A 只需要知道 `GlobalEventBus` 和事件类，而无需知道模块 B 的存在，即可实现与模块 B 的交互。

---

## 4. API 使用指南

由于 `GlobalEventBus` 是对 `EventBus` 的静态引用，其主要操作均通过 `EVENT_BUS` 成员完成。

| 操作类型 | 代码示例 | 说明 |
| :--- | :--- | :--- |
| **注册监听** | `GlobalEventBus.EVENT_BUS.register(this);` | 在组件初始化（如 `onInit`）时调用。 |
| **发送事件** | `GlobalEventBus.EVENT_BUS.post(new ConfigChangedEvent());` | 在任何业务逻辑发生点触发。 |
| **取消注册** | `GlobalEventBus.EVENT_BUS.unregister(this);` | 在组件销毁（如 `onDestroy`）时调用，防止内存泄漏。 |

---

## 5. 最佳实践

### 5.1 何时使用 GlobalEventBus？
*   **全局生命周期事件**: 如用户登录/登出、系统配置刷新。
*   **跨层级通信**: 例如底层的网络模块需要通知最顶层的 UI 界面显示通知。
*   **临时任务**: 不需要长期维护引用关系的瞬时事件处理。

### 5.2 注意事项
1.  **内存管理**: 凡是使用 `GlobalEventBus.EVENT_BUS.register()` 的对象，必须在生命周期结束时手动调用 `unregister()`，否则该对象将因为被全局静态引用持有而无法被 JVM 回收。
2.  **性能考量**: 虽然单次分发效率很高，但若全局总线上挂载了数千个监听器，频繁发布高频事件（如鼠标移动）可能会产生性能抖动。

---

## 6. 使用代码示例

### 场景：全局错误处理系统
```java
// 1. 定义全局异常事件
public class GlobalErrorEvent {
    public final String message;
    public GlobalErrorEvent(String msg) { this.message = msg; }
}

// 2. 在 UI 层注册监听
public class MainNotificationUI {
    public MainNotificationUI() {
        GlobalEventBus.EVENT_BUS.register(this);
    }

    @SubscribeEvent
    public void onErrorMessage(GlobalErrorEvent event) {
        showToast("系统错误: " + event.message);
    }
}

// 3. 在底层业务逻辑处发布
public class DatabaseWorker {
    public void doWork() {
        try {
            // 某些业务操作...
        } catch (Exception e) {
            // 发现错误，直接向全局总线抛出，无需持有 UI 的引用
            GlobalEventBus.EVENT_BUS.post(new GlobalErrorEvent(e.getMessage()));
        }
    }
}
```

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