mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-26 06:16:43 +08:00
a79f02c987
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件 - 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明 - 提供完整的 API 使用示例路径、最佳实践与性能建议 - 包含架构图、依赖关系图与故障排查指南 - 添加测试用例参考与扩展方法说明 - [skip ci]
19 KiB
19 KiB
事件总线模式
**本文引用的文件** - [EventBus.cs](file://GFramework.Core/events/EventBus.cs) - [EasyEvent.cs](file://GFramework.Core/events/EasyEvent.cs) - [EasyEventGeneric.cs](file://GFramework.Core/events/EasyEventGeneric.cs) - [EasyEvents.cs](file://GFramework.Core/events/EasyEvents.cs) - [OrEvent.cs](file://GFramework.Core/events/OrEvent.cs) - [DefaultUnRegister.cs](file://GFramework.Core/events/DefaultUnRegister.cs) - [UnRegisterList.cs](file://GFramework.Core/events/UnRegisterList.cs) - [UnRegisterListExtension.cs](file://GFramework.Core/extensions/UnRegisterListExtension.cs) - [IEventBus.cs](file://GFramework.Core.Abstractions/events/IEventBus.cs) - [IEvent.cs](file://GFramework.Core.Abstractions/events/IEvent.cs) - [ArchitectureEvents.cs](file://GFramework.Core/events/ArchitectureEvents.cs) - [EventBusTests.cs](file://GFramework.Core.Tests/events/EventBusTests.cs) - [advanced-patterns.md](file://docs/tutorials/advanced-patterns.md) - [README.md（核心框架）](file://GFramework.Core/README.md) - [SettingsChangedEvent.cs](file://GFramework.Game/setting/events/SettingsChangedEvent.cs) - [SettingsSavedEvent.cs](file://GFramework.Game/setting/events/SettingsSavedEvent.cs)目录
引言
本教程围绕 GFramework 的事件总线模式展开，系统讲解事件总线的设计架构与实现机制，涵盖事件处理器的注册与管理、同步与异步事件处理差异、事件路由与分发策略；并结合框架内现有实现，说明事件处理器接口设计（IEventBus、IEvent）、事件订阅与取消订阅的生命周期管理，以及异常处理与错误恢复机制。最后给出游戏开发中的典型应用案例与最佳实践。
项目结构
事件总线相关代码主要位于 GFramework.Core 的 events 与 extensions 子目录，并通过抽象接口定义在 Core.Abstractions 中，形成“抽象定义 + 具体实现 + 扩展工具”的分层组织：
- 抽象接口层：定义事件总线与事件的契约
- 实现层：提供基于类型的事件系统与事件管理器
- 扩展层：提供注销列表与便捷扩展方法
- 测试层：验证事件总线的注册、注销与分发行为
- 文档与示例：高级模式文档与游戏设置事件示例
graph TB
subgraph "抽象接口层"
IEventBus["IEventBus.cs"]
IEvent["IEvent.cs"]
end
subgraph "实现层"
EventBus["EventBus.cs"]
EasyEvents["EasyEvents.cs"]
EasyEvent["EasyEvent.cs"]
EasyEventGeneric["EasyEventGeneric.cs"]
OrEvent["OrEvent.cs"]
DefaultUnRegister["DefaultUnRegister.cs"]
UnRegisterList["UnRegisterList.cs"]
end
subgraph "扩展层"
UnRegisterListExt["UnRegisterListExtension.cs"]
end
subgraph "测试层"
EventBusTests["EventBusTests.cs"]
end
subgraph "文档与示例"
AdvPatterns["advanced-patterns.md"]
ArchEvents["ArchitectureEvents.cs"]
SettingsChanged["SettingsChangedEvent.cs"]
SettingsSaved["SettingsSavedEvent.cs"]
CoreReadme["README.md核心框架"]
end
IEventBus --> EventBus
IEvent --> EasyEvent
IEvent --> EasyEventGeneric
EventBus --> EasyEvents
EventBus --> EasyEvent
EventBus --> EasyEventGeneric
OrEvent --> DefaultUnRegister
UnRegisterList --> DefaultUnRegister
UnRegisterListExt --> UnRegisterList
EventBusTests --> EventBus
AdvPatterns --> EventBus
SettingsChanged --> EventBus
SettingsSaved --> EventBus
ArchEvents --> EventBus
图表来源
- IEventBus.cs
- IEvent.cs
- EventBus.cs
- EasyEvents.cs
- EasyEvent.cs
- EasyEventGeneric.cs
- OrEvent.cs
- DefaultUnRegister.cs
- UnRegisterList.cs
- UnRegisterListExtension.cs
- EventBusTests.cs
- advanced-patterns.md
- ArchitectureEvents.cs
- SettingsChangedEvent.cs
- SettingsSavedEvent.cs
- README.md（核心框架）
章节来源
核心组件
- IEventBus：事件总线接口，定义 Send、Register、UnRegister 等能力
- EventBus：IEventBus 的具体实现，基于 EasyEvents 管理事件
- EasyEvents：全局事件管理器，按类型缓存事件实例，支持 Get、GetOrAdd、Add、GetEvent 等
- EasyEvent / Event / Event<T,TK>：事件载体，支持注册、注销、触发，内置空操作委托避免空检查
- OrEvent：事件“或”组合器，将多个事件合并为一个触发源
- DefaultUnRegister / UnRegisterList：注销器与注销列表，统一管理生命周期
- UnRegisterListExtension：扩展方法，提供 AddToUnregisterList 与 UnRegisterAll
章节来源
- IEventBus.cs
- EventBus.cs
- EasyEvents.cs
- EasyEvent.cs
- EasyEventGeneric.cs
- OrEvent.cs
- DefaultUnRegister.cs
- UnRegisterList.cs
- UnRegisterListExtension.cs
架构总览
事件总线采用“基于类型的事件系统”，通过 EventBus 将 Send、Register、UnRegister 三类操作桥接到 EasyEvents 管理的事件实例上。事件实例由 EasyEvent 或 Event 等承载，内部使用委托聚合与空操作委托实现高效触发与安全注销。
classDiagram
class IEventBus {
+Send~T~()
+Send~T~(e)
+Register~T~(onEvent) IUnRegister
+UnRegister~T~(onEvent)
}
class EventBus {
-_mEvents : EasyEvents
+Send~T~()
+Send~T~(e)
+Register~T~(onEvent) IUnRegister
+UnRegister~T~(onEvent)
}
class EasyEvents {
-_mTypeEvents : Dictionary
+Get~T~() T
+Register~T~()
+GetOrAdd~T~() T
+AddEvent~T~()
+GetEvent~T~() T
}
class IEvent {
+Register(onEvent) IUnRegister
}
class EasyEvent {
-_mOnEvent : Action
+Register(onEvent) IUnRegister
+UnRegister(onEvent)
+Trigger()
}
class Event_T_ {
-_mOnEvent : Action~T~
+Register(onEvent) IUnRegister
+UnRegister(onEvent)
+Trigger(t)
}
class OrEvent {
-_mOnEvent : Action
+Or(event) OrEvent
+Register(onEvent) IUnRegister
+UnRegister(onEvent)
-Trigger()
}
class DefaultUnRegister {
-_mOnUnRegister : Action
+UnRegister()
}
class UnRegisterList {
-_unRegisterList : IUnRegister[]
+Add(unRegister)
+UnRegisterAll()
}
IEventBus <|.. EventBus
EventBus --> EasyEvents : "管理事件"
EasyEvents --> EasyEvent : "缓存/获取"
EasyEvents --> Event_T_ : "缓存/获取"
OrEvent --> DefaultUnRegister : "组合注销"
UnRegisterList --> DefaultUnRegister : "管理"
IEvent <|.. EasyEvent
IEvent <|.. Event_T_
图表来源
- IEventBus.cs
- EventBus.cs
- EasyEvents.cs
- EasyEvent.cs
- EasyEventGeneric.cs
- OrEvent.cs
- DefaultUnRegister.cs
- UnRegisterList.cs
- IEvent.cs
详细组件分析
事件总线接口与实现（IEventBus / EventBus）
- IEventBus 定义了 Send、Register、UnRegister 的契约，支持泛型事件类型与实例发送
- EventBus 将接口委托给 EasyEvents 管理的事件实例，实现类型安全的事件分发
sequenceDiagram
participant Caller as "调用方"
participant Bus as "EventBus"
participant Events as "EasyEvents"
participant Evt as "Event<T>"
participant Handler as "处理器"
Caller->>Bus : "Register<T>(onEvent)"
Bus->>Events : "GetOrAddEvent<Event<T>>()"
Events-->>Bus : "Event<T> 实例"
Bus->>Evt : "Register(onEvent)"
Evt-->>Caller : "IUnRegister"
Caller->>Bus : "Send<T>() / Send<T>(e)"
Bus->>Events : "GetOrAddEvent<Event<T>>()"
Bus->>Evt : "Trigger(e)"
Evt-->>Handler : "onEvent(e)"
图表来源
章节来源
事件管理器（EasyEvents）
- 提供静态入口与实例入口，支持按类型获取或添加事件
- 内部以类型到事件实例的字典缓存，避免重复创建
- 支持注册、获取、添加、获取或添加等操作
章节来源
事件载体（EasyEvent / Event / Event<T,TK>）
- EasyEvent：无参事件，支持注册、注销、触发
- Event / Event<T,TK>：带参事件，显式实现 IEvent.Register(Action)，允许无参订阅
- 内部使用空操作委托避免空检查，提升触发效率
章节来源
事件组合（OrEvent）
- OrEvent 将多个事件通过“或”逻辑组合，任一事件触发即触发自身
- 通过扩展方法将子事件的注销加入自身注销列表，统一管理
章节来源
注销机制（DefaultUnRegister / UnRegisterList）
- DefaultUnRegister 在 UnRegister() 时执行回调并清理引用，防止重复注销
- UnRegisterList 统一收集多个注销对象，支持批量注销与清空
章节来源
同步与异步事件处理（对比与扩展）
- 框架现有实现为同步事件处理（EventBus、Event、EasyEvent）
- 高级模式文档展示了异步事件处理的扩展思路：分别维护同步/异步处理器集合，发布时先处理同步处理器，再并发等待异步处理器完成，并对异常进行隔离
flowchart TD
Start(["开始发布事件"]) --> Persist["持久化事件可选"]
Persist --> Split{"是否存在同步/异步处理器？"}
Split --> |同步| SyncLoop["遍历同步处理器<br/>try-catch 隔离异常"]
Split --> |异步| AsyncLoop["收集异步处理器任务"]
SyncLoop --> AsyncLoop
AsyncLoop --> AwaitAll{"是否有异步任务？"}
AwaitAll --> |是| WaitAll["Task.WhenAll 等待完成"]
AwaitAll --> |否| End(["结束"])
WaitAll --> End
图表来源
章节来源
事件处理器接口设计（IEventHandler / IAsyncEventHandler）
- 高级模式文档定义了 IEventHandler 与 IAsyncEventHandler，用于区分同步与异步处理
- 事件总线实现中未直接暴露这些接口，但可通过扩展实现兼容
章节来源
事件订阅与取消订阅生命周期管理
- 注册返回 IUnRegister，调用 UnRegister() 即可注销
- 使用 UnRegisterList 收集多个注销对象，可在组件销毁时统一注销
- 扩展方法 AddToUnregisterList 与 UnRegisterAll 简化管理
章节来源
事件路由与分发策略
- 基于类型路由：EventBus 通过 EasyEvents 按类型获取事件实例，确保同类型事件共享同一处理器集合
- 分发策略：事件触发时依次调用已注册的处理器，保持顺序一致性
- 组合事件：OrEvent 将多个事件合并，简化订阅端逻辑
章节来源
异常处理与错误恢复
- 现有实现中，事件触发采用空操作委托，避免空引用导致的异常扩散
- 高级模式文档建议在异步发布时对处理器异常进行 try-catch 隔离，保证其他处理器正常执行
- 建议在业务层对关键处理器增加重试或降级策略
章节来源
实际游戏开发应用案例
- 玩家行为响应：通过事件系统监听输入或状态变化，触发相应处理（如移动、攻击、拾取）
- 游戏状态更新：模型层状态变化通过事件通知控制器与系统，实现 UI 与逻辑同步
- UI 事件处理：UI 层通过事件与系统解耦，避免直接依赖具体实现
章节来源
架构事件（ArchitectureEvents）
- 提供架构生命周期相关事件结构体，便于在架构初始化、销毁阶段进行监控与处理
章节来源
设置系统事件（Settings*Event）
- SettingsChangedEvent 与 SettingsSavedEvent 展示了泛型事件在游戏设置模块中的应用，携带变更时间与类型化设置实例
章节来源
依赖分析
事件总线模块内部依赖关系清晰，接口与实现分离，扩展方法与注销机制相互配合，形成低耦合、高内聚的事件系统。
graph LR
IEventBus["IEventBus.cs"] --> EventBus["EventBus.cs"]
EventBus --> EasyEvents["EasyEvents.cs"]
EasyEvents --> EasyEvent["EasyEvent.cs"]
EasyEvents --> Event_T_["EasyEventGeneric.cs"]
OrEvent["OrEvent.cs"] --> DefaultUnRegister["DefaultUnRegister.cs"]
UnRegisterList["UnRegisterList.cs"] --> DefaultUnRegister
UnRegisterListExt["UnRegisterListExtension.cs"] --> UnRegisterList
EventBusTests["EventBusTests.cs"] --> EventBus
图表来源
- IEventBus.cs
- EventBus.cs
- EasyEvents.cs
- EasyEvent.cs
- EasyEventGeneric.cs
- OrEvent.cs
- DefaultUnRegister.cs
- UnRegisterList.cs
- UnRegisterListExtension.cs
- EventBusTests.cs
章节来源
性能考量
- 事件触发采用空操作委托，避免空引用检查开销
- 事件实例按类型缓存，减少重复创建
- 建议避免高频事件（如每帧触发），优先使用可绑定属性或批处理
- 异步处理器建议使用并发等待并在异常隔离下执行
章节来源
故障排查指南
- 注销未生效：确认是否正确调用 IUnRegister.UnRegister() 或通过 UnRegisterList.UnRegisterAll() 批量注销
- 事件未触发：检查事件类型是否一致、是否使用 GetOrAddEvent 获取同一实例
- 内存泄漏：确保组件销毁时统一注销，避免持有事件引用
- 异步异常：参考高级模式文档，对异步处理器异常进行隔离处理
章节来源
结论
GFramework 的事件总线通过“接口 + 实现 + 扩展”的分层设计，提供了类型安全、低耦合、易管理的事件系统。结合注销列表与扩展方法，能够有效管理生命周期；通过架构事件与游戏模块事件，进一步完善了事件在整体架构中的作用。对于需要异步处理与更强健的异常隔离场景，可参考高级模式文档进行扩展实现。
附录
- 事件总线使用要点
- 使用 EventBus.Register() 订阅事件，返回 IUnRegister 以便注销
- 使用 EventBus.Send() 或 Send(e) 发布事件
- 使用 UnRegisterList 统一管理多个注销对象
- 对高频事件与异步处理器进行性能与异常优化
章节来源