tzdwindows 7
7badbb0d8e
- 新增浏览器模块技术文档，涵盖 BrowserCore、BrowserWindow 等核心组件 - 添加事件系统文档，包括 EventBus、GlobalEventBus 及各类事件定义 - 创建 LanguageManager 国际化管理器详细说明文档 - 新增 Log4j2OutputStream 标准输出重定向类文档 - 添加 Main 入口类启动流程与路由机制说明 - 创建 BrowserCreationCallback 回调接口使用指南 - 完善 AxisInnovatorsBox 主类架构与崩溃诊断系统文档
102 lines
3.7 KiB
Markdown
102 lines
3.7 KiB
Markdown
# 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` 生效，标记的方法必须遵循以下约束：
|
||
|
||
1. **参数限制**: 方法必须有且仅有一个参数。该参数的类型即为该监听器关注的事件类型。
|
||
2. **访问权限**: 虽然 `EventBus` 内部通过 `setAccessible(true)` 支持私有方法，但建议根据模块化设计合理设置方法的可见性。
|
||
3. **返回类型**: 通常为 `void`。因为事件发布是单向的分发过程，`EventBus` 不会处理监听方法的返回值。
|
||
|
||
---
|
||
|
||
## 5. 使用示例
|
||
|
||
### 5.1 基础用法
|
||
```java
|
||
@SubscribeEvent
|
||
public void onGenericEvent(MessageEvent event) {
|
||
System.out.println("收到消息: " + event.getContent());
|
||
}
|
||
```
|
||
|
||
### 5.2 优先级应用场景
|
||
假设有一个日志系统，需要在业务逻辑处理前记录日志，在业务逻辑处理后进行清理：
|
||
|
||
```java
|
||
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 的工作流程
|
||
|
||
1. **扫描**: `EventBus.register(obj)` 被调用。
|
||
2. **识别**: 遍历 `obj` 及其父类，筛选出所有带有 `@SubscribeEvent` 的方法。
|
||
3. **解析**: 读取 `priority` 数值以及参数类型。
|
||
4. **排序**: 将这些信息封装为 `Subscriber` 对象并根据优先级存入订阅列表。
|
||
5. **分发**: `post(event)` 时，按优先级从高到低依次反射调用。
|
||
|
||
---
|
||
*文档生成时间: 2026-01-02* |