Package top.magstar.framework.events.annotations

package top.magstar.framework.events.annotations
事件总线注解包

本包提供了事件总线系统所需的核心注解，用于声明事件监听器、配置事件处理行为， 以及实现 Bukkit 事件到自定义事件的桥接。

核心注解

Bukkit 事件桥接注解

使用示例

基础事件监听


 @EventListener
 public void onPlayerJoin(PlayerJoinEvent event) {
     Player player = event.getPlayer();
     System.out.println(player.getName() + " 加入了游戏");
 }

优先级控制


 @EventListener(priority = Priority.HIGH)
 public void onPlayerQuit(PlayerQuitEvent event) {
     // 高优先级处理器，会比普通处理器更早执行
     savePlayerData(event.getPlayer());
 }

异步处理


 @EventListener(async = true)
 @AsyncHandler(threadPool = "database", timeout = 10000)
 public void onPlayerChat(PlayerChatEvent event) {
     // 异步保存聊天记录到数据库
     chatRepository.save(new ChatRecord(event));
 }

Bukkit 事件桥接


 @AutoBridge(verbose = true)
 public class PlayerEventBridge {

     @BridgeMapping(priority = EventPriority.HIGH)
     public PlayerJoinEvent mapJoinEvent(org.bukkit.event.player.PlayerJoinEvent bukkit) {
         return new PlayerJoinEvent(bukkit.getPlayer(), bukkit.getJoinMessage());
     }

     @BridgeMapping(ignoreCancelled = true, async = true)
     public PlayerChatEvent mapChatEvent(org.bukkit.event.player.AsyncPlayerChatEvent bukkit) {
         return new PlayerChatEvent(bukkit.getPlayer(), bukkit.getMessage());
     }
 }

直接桥接


 @DirectBridge(
     value = {
         org.bukkit.event.player.PlayerJoinEvent.class,
         org.bukkit.event.player.PlayerQuitEvent.class,
         org.bukkit.event.player.PlayerKickEvent.class
     },
     priority = EventPriority.NORMAL,
     async = false
 )
 public class PlayerEventDirectBridge {
     // 无需编写任何代码，框架会自动桥接这些事件
 }

注解组合使用

多个注解可以组合使用以实现复杂的事件处理逻辑： 


 @EventListener(priority = 10, ignoreCancelled = true)
 @AsyncHandler(threadPool = "heavy-tasks", timeout = 30000)
 public void onBlockBreak(BlockBreakEvent event) {
     // 高优先级、异步、忽略已取消事件
     performHeavyCalculation(event.getBlock());
 }

优先级说明

事件处理器按照优先级顺序执行，数字越小优先级越高：

优先级常量
常量 值 说明
Priority.HIGHEST 0 最高优先级，最先执行
Priority.HIGH 25 高优先级
Priority.NORMAL 50 普通优先级（默认）
Priority.LOW 75 低优先级
Priority.LOWEST 100 最低优先级
Priority.MONITOR 1000 监控级别，最后执行，不应修改事件状态

异步处理注意事项

  • 线程安全：异步处理器需要注意线程安全问题
  • 超时处理：设置合理的超时时间，避免任务无限等待
  • 异常处理：异步任务中的异常不会影响主线程
  • 资源管理：合理配置线程池大小，避免资源耗尽

Bukkit 事件桥接机制

事件桥接允许将 Bukkit 原生事件转换为自定义事件对象：

  • 自动桥接：通过 AutoBridge 和 BridgeMapping 定义映射方法
  • 直接桥接：通过 DirectBridge 直接转发原始事件
  • 优先级控制：可以控制桥接监听器的执行顺序
  • 异步发布：支持异步发布转换后的事件

最佳实践

  1. 合理使用优先级：根据业务逻辑的依赖关系设置优先级
  2. 避免阻塞：在同步处理器中避免长时间阻塞操作
  3. 异步优先：对于耗时操作优先考虑异步处理
  4. 错误处理：始终处理可能的异常，避免影响其他监听器
  5. 性能监控：使用 Priority.MONITOR 优先级记录性能数据
  6. 职责单一：每个监听器方法只处理一个明确的业务逻辑
  7. 文档完善：为复杂的事件处理逻辑编写详细的注释
Since:
1.0.0
Version:
1.0.0
Author:
MagStar Framework Team
See Also: