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

GlobalEventBus 类技术文档

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

---

1. 概述

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

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

2. 核心架构设计

2.1 单例模式 (Singleton)

该类采用了最简洁的静态常量初始化方式：

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

场景：全局错误处理系统

// 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