# 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*