Files

tzdwindows 7 7badbb0d8e docs: 添加 Axis Innovators Box 框架完整 API 文档

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

2026-01-03 08:46:19 +08:00

3.7 KiB

Raw Blame History

SubscribeEvent 注解技术文档

包路径: com.axis.innovators.box.events.SubscribeEvent
主要功能: 标记事件订阅方法并定义执行优先级
作者: tzdwindows 7

1. 概述

@SubscribeEvent 是 Axis Innovators Box 事件系统的核心元数据注解。它被用于标记类中的方法，使其能够被 EventBus 识别并注册为事件监听器（Listener）。

该注解的存在实现了“声明式”的事件监听。开发者无需实现复杂的接口，只需在任意方法上添加此注解，并确保方法签名符合规范（单参数），即可自动参与系统的事件流转。

2. 注解配置说明

2.1 运行时保留 (`@Retention`)

设置为 RetentionPolicy.RUNTIME。这意味着注解信息在类加载后依然保留在 JVM 中，允许 EventBus 在运行时通过**反射（Reflection）**动态扫描到这些方法。

2.2 目标范围 (`@Target`)

设置为 ElementType.METHOD。明确限定该注解仅能用于方法上。

3. 核心属性详解

3.1 `priority()`

类型: int
默认值: 0
功能: 定义事件处理的先后顺序。
逻辑规则:
- 当一个事件被发布时，EventBus 会根据所有订阅该事件的方法的 priority 值进行排序。
- 值越大，优先级越高，该方法将越早接收到事件通知。
- 当优先级相同时，执行顺序取决于系统反射获取方法的自然顺序（通常不保证固定顺序）。

4. 订阅方法规范

为了使 @SubscribeEvent 生效，标记的方法必须遵循以下约束：

参数限制: 方法必须有且仅有一个参数。该参数的类型即为该监听器关注的事件类型。
访问权限: 虽然 EventBus 内部通过 setAccessible(true) 支持私有方法，但建议根据模块化设计合理设置方法的可见性。
返回类型: 通常为 void。因为事件发布是单向的分发过程，EventBus 不会处理监听方法的返回值。

5. 使用示例

5.1 基础用法

@SubscribeEvent
public void onGenericEvent(MessageEvent event) {
    System.out.println("收到消息: " + event.getContent());
}

5.2 优先级应用场景

假设有一个日志系统，需要在业务逻辑处理前记录日志，在业务逻辑处理后进行清理：

public class SecurityMonitor {
    // 高优先级：先检查权限
    @SubscribeEvent(priority = 100)
    public void checkPermission(UserActionEvent event) {
        if (!event.user.hasAccess()) {
            event.setCancelled(true);
        }
    }
}

public class BusinessLogic {
    // 默认优先级：正常执行业务
    @SubscribeEvent(priority = 0)
    public void handleAction(UserActionEvent event) {
        if (!event.isCancelled()) {
            executeTask();
        }
    }
}

6. 技术亮点

非侵入式设计: 业务类不需要继承任何父类或实现特定接口，保持了代码的纯净性。
精细化控制: 通过 priority 属性，解决了传统观察者模式中监听器执行顺序不可控的问题。
自描述性: 开发者通过阅读代码中的注解，可以清晰地识别出哪些逻辑是响应式的，增强了代码的可读性。

7. 配合 EventBus 的工作流程

扫描: EventBus.register(obj) 被调用。
识别: 遍历 obj 及其父类，筛选出所有带有 @SubscribeEvent 的方法。
解析: 读取 priority 数值以及参数类型。
排序: 将这些信息封装为 Subscriber 对象并根据优先级存入订阅列表。
分发: post(event) 时，按优先级从高到低依次反射调用。

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

3.7 KiB Raw Blame History Unescape Escape