GFramework/.qoder/repowiki/zh/content/核心架构模块/核心架构模块.md

核心架构模块

**本文引用的文件** - [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs) - [ArchitectureContext.cs](file://GFramework.Core/architecture/ArchitectureContext.cs) - [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs) - [EventBus.cs](file://GFramework.Core/events/EventBus.cs) - [EasyEvent.cs](file://GFramework.Core/events/EasyEvent.cs) - [EasyEvents.cs](file://GFramework.Core/events/EasyEvents.cs) - [CommandBus.cs](file://GFramework.Core/command/CommandBus.cs) - [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs) - [QueryBus.cs](file://GFramework.Core/query/QueryBus.cs) - [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs) - [CoroutineScheduler.cs](file://GFramework.Core/coroutine/CoroutineScheduler.cs) - [CoroutineHandle.cs](file://GFramework.Core/coroutine/CoroutineHandle.cs) - [WaitForFrames.cs](file://GFramework.Core/coroutine/WaitForFrames.cs) - [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs) - [ConsoleLoggerFactory.cs](file://GFramework.Core/logging/ConsoleLoggerFactory.cs)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考量
8. 故障排查指南
9. 结论
10. 附录

简介

本文件面向GFramework核心架构模块，系统化梳理以下能力：

• 架构管理系统：Architecture基类的设计模式、生命周期管理机制与组件注册体系
• 事件系统：EventBus的类型安全实现、EasyEvent机制与事件传播
• 命令查询分离（CQRS）：CommandBus/QueryBus实现、异步处理与输入输出模型
• 协程调度系统：CoroutineScheduler工作原理、YieldInstruction机制与性能优化
• 依赖注入：IocContainer生命周期与服务注册解析
• 日志系统：结构化设计与多级别支持
• API参考、使用示例与最佳实践
• 设计决策与权衡

项目结构

核心模块位于GFramework.Core，采用“按职责分层+按领域聚合”的组织方式：

• architecture：架构基类、上下文、服务装配与配置
• events：事件总线与易用事件容器
• command/query：命令与查询总线及抽象基类
• coroutine：协程调度器与等待指令
• ioc：依赖注入容器
• logging：日志工厂与记录器
• abstractions：各模块的接口契约

graph TB
subgraph "架构层"
A["Architecture<br/>生命周期与阶段管理"]
ACtx["ArchitectureContext<br/>服务门面"]
ASvc["ArchitectureServices<br/>服务装配"]
end
subgraph "事件系统"
EB["EventBus"]
EE["EasyEvents"]
Evt["EasyEvent"]
end
subgraph "CQRS"
CB["CommandBus"]
QB["QueryBus"]
Cmd["AbstractCommand"]
Qry["AbstractQuery"]
end
subgraph "协程"
CS["CoroutineScheduler"]
CH["CoroutineHandle"]
WF["WaitForFrames"]
end
subgraph "DI"
IOC["IocContainer"]
end
subgraph "日志"
LF["ConsoleLoggerFactory"]
end
A --> ACtx
A --> ASvc
ASvc --> IOC
ASvc --> EB
ASvc --> CB
ASvc --> QB
ACtx --> EB
ACtx --> CB
ACtx --> QB
EB --> EE
EE --> Evt
CB --> Cmd
QB --> Qry
CS --> CH
CS --> WF
LF --> A

图表来源

• Architecture.cs
• ArchitectureContext.cs
• ArchitectureServices.cs
• EventBus.cs
• EasyEvents.cs
• EasyEvent.cs
• CommandBus.cs
• AbstractCommand.cs
• QueryBus.cs
• AbstractQuery.cs
• CoroutineScheduler.cs
• CoroutineHandle.cs
• WaitForFrames.cs
• IocContainer.cs
• ConsoleLoggerFactory.cs

章节来源

• Architecture.cs
• ArchitectureContext.cs
• ArchitectureServices.cs

核心组件

• Architecture：统一的架构基类，负责阶段管理、组件注册、生命周期编排与销毁
• ArchitectureContext：服务门面，封装命令/查询/事件/系统/模型/工具的获取与执行
• ArchitectureServices：服务装配中心，统一创建并注册EventBus、CommandBus、QueryBus、AsyncQueryBus与IocContainer
• EventBus/EasyEvents/EasyEvent：类型安全事件系统，支持泛型事件自动创建与触发
• CommandBus/AbstractCommand：命令总线与抽象命令基类，支持同步/异步命令与返回值
• QueryBus/AbstractQuery：查询总线与抽象查询基类，支持同步查询
• CoroutineScheduler/CoroutineHandle/WaitForFrames：协程调度器与等待指令，支持暂停/恢复/等待/按标签终止
• IocContainer：线程安全的依赖注入容器，支持单例/多重注册、冻结保护与排序获取
• ConsoleLoggerFactory：日志工厂，提供控制台日志记录器

章节来源

• EventBus.cs
• EasyEvents.cs
• EasyEvent.cs
• CommandBus.cs
• AbstractCommand.cs
• QueryBus.cs
• AbstractQuery.cs
• CoroutineScheduler.cs
• CoroutineHandle.cs
• WaitForFrames.cs
• IocContainer.cs
• ConsoleLoggerFactory.cs

架构总览

下图展示Architecture如何通过ArchitectureServices装配核心服务，并由ArchitectureContext提供统一的服务门面，同时协调事件、命令、查询与协程等子系统。

sequenceDiagram
participant App as "应用代码"
participant Arch as "Architecture"
participant Ctx as "ArchitectureContext"
participant Svc as "ArchitectureServices"
participant IOC as "IocContainer"
participant EB as "EventBus"
participant CB as "CommandBus"
participant QB as "QueryBus"
App->>Arch : Initialize()/InitializeAsync()
Arch->>Svc : 构造并注册服务
Svc->>IOC : RegisterPlurality(...)
Svc->>EB : new EventBus()
Svc->>CB : new CommandBus()
Svc->>QB : new QueryBus()
Arch->>Ctx : new ArchitectureContext(IOC)
Arch->>Arch : EnterPhase(Ready)
Arch->>EB : Send(ArchitectureLifecycleReadyEvent)
App-->>Ctx : 通过Context执行命令/查询/事件
Ctx->>CB : Send(...)
Ctx->>QB : Send(...)
Ctx->>EB : Send/Register/UnRegister(...)

图表来源

• Architecture.cs
• ArchitectureServices.cs
• ArchitectureContext.cs
• EventBus.cs
• CommandBus.cs
• QueryBus.cs

详细组件分析

Architecture：架构基类与生命周期

• 设计模式
  • 组合优于继承：通过组合ArchitectureServices与IocContainer，集中管理服务与依赖
  • 职责分离：生命周期管理、阶段转换、组件注册与初始化解耦于具体业务
• 生命周期管理
  • 阶段模型：BeforeUtilityInit → AfterUtilityInit → BeforeModelInit → AfterModelInit → BeforeSystemInit → AfterSystemInit → Ready → Destroying → Destroyed
  • 阶段转换校验：受配置项控制，支持严格校验与宽松校验
  • 阶段感知：IArchitecturePhaseAware与IArchitectureLifecycle钩子在阶段切换时被通知
• 组件注册
  • 支持系统、模型、工具注册，自动注入上下文并登记生命周期
  • 注册时机限制：Ready之后默认禁止注册（可通过配置放宽）
• 初始化与销毁
  • Initialize/InitializeAsync：按阶段顺序初始化工具/模型/系统，随后冻结容器并进入Ready
  • Destroy：逆序销毁IDisposable组件，阶段推进至Destroyed并广播事件

flowchart TD
Start(["进入 InitializeInternalAsync"]) --> Cfg["设置日志工厂/初始化环境"]
Cfg --> Ctx["创建/绑定 ArchitectureContext"]
Ctx --> UserInit["调用子类 Init()"]
UserInit --> Group["按类型分组：工具/模型/系统"]
Group --> U1["BeforeUtilityInit"]
U1 --> U2["AfterUtilityInit"]
U2 --> M1["BeforeModelInit"]
M1 --> M2["AfterModelInit"]
M2 --> S1["BeforeSystemInit"]
S1 --> S2["AfterSystemInit"]
S2 --> Freeze["Container.Freeze()"]
Freeze --> Ready["EnterPhase(Ready)<br/>广播 Ready 事件"]
Ready --> End(["完成"])

图表来源

• Architecture.cs
• Architecture.cs

章节来源

• Architecture.cs

ArchitectureContext：服务门面与执行入口

• 服务缓存：首次获取通过容器解析并缓存，后续直接命中
• 命令执行：SendCommand/SendCommandAsync，支持同步/异步与返回值
• 查询执行：SendQuery/SendQueryAsync，支持同步/异步查询
• 事件管理：SendEvent/RegisterEvent/UnRegisterEvent
• 组件检索：GetSystem/GetModel/GetUtility
• 环境获取：GetEnvironment

classDiagram
class ArchitectureContext {
-IIocContainer _container
-Dictionary~Type,object~ _serviceCache
+GetService<T>()
+SendQuery<TResult>(IQuery<TResult>)
+SendQueryAsync<TResult>(IAsyncQuery<TResult>)
+SendCommand(ICommand)
+SendCommand<TResult>(ICommand<TResult>)
+SendCommandAsync(IAsyncCommand)
+SendCommandAsync<TResult>(IAsyncCommand<TResult>)
+SendEvent<TEvent>()
+SendEvent<TEvent>(TEvent)
+RegisterEvent<TEvent>(Action<TEvent>) IUnRegister
+UnRegisterEvent<TEvent>(Action<TEvent>)
+GetSystem<TSystem>()
+GetModel<TModel>()
+GetUtility<TUtility>()
+GetEnvironment() IEnvironment
}

图表来源

• ArchitectureContext.cs

章节来源

• ArchitectureContext.cs

ArchitectureServices：服务装配中心

• 职责：创建并注册EventBus、CommandBus、QueryBus、AsyncQueryBus与IocContainer
• 上下文绑定：SetContext将架构上下文传递给容器与服务
• 服务暴露：Container/EventBus/CommandBus/QueryBus/AsyncQueryBus属性

classDiagram
class ArchitectureServices {
-IAsyncQueryBus _asyncQueryBus
-ICommandBus _commandBus
-IIocContainer _container
-IEventBus _eventBus
-IQueryBus _queryBus
-IArchitectureContext _context
+Container : IIocContainer
+EventBus : IEventBus
+CommandBus : ICommandBus
+QueryBus : IQueryBus
+AsyncQueryBus : IAsyncQueryBus
+SetContext(context)
+GetContext()
}
ArchitectureServices --> IocContainer : "组合"
ArchitectureServices --> EventBus : "组合"
ArchitectureServices --> CommandBus : "组合"
ArchitectureServices --> QueryBus : "组合"
ArchitectureServices --> AsyncQueryBus : "组合"

图表来源

• ArchitectureServices.cs

章节来源

• ArchitectureServices.cs

事件系统：EventBus/EasyEvent/EasyEvents

• 类型安全：EventBus.Send()与Send(T)均基于泛型事件类型Event，通过EasyEvents统一管理
• 易用性：EasyEvent/EasyEvents提供简单事件与全局事件容器，支持自动创建与注册
• 传播机制：EventBus内部委托链触发，支持注册/注销与按类型分发

sequenceDiagram
participant Sender as "发送方"
participant EB as "EventBus"
participant EE as "EasyEvents"
participant EVT as "Event<T>"
participant Handler as "监听者"
Sender->>EB : Send<TEvent>()
EB->>EE : GetOrAddEvent<Event<TEvent>>()
EE-->>EB : Event<TEvent> 实例
EB->>EVT : Trigger(new TEvent())
EVT-->>Handler : 回调执行
Sender->>EB : Register<TEvent>(Action)
EB->>EVT : Register(Action)
Sender->>EB : UnRegister<TEvent>(Action)
EB->>EVT : UnRegister(Action)

图表来源

• EventBus.cs
• EasyEvents.cs
• EasyEvent.cs

章节来源

• EventBus.cs
• EasyEvents.cs
• EasyEvent.cs

命令查询分离（CQRS）：CommandBus/QueryBus 与抽象基类

• 命令总线
  • 同步：Send(ICommand)/Send(ICommand)
  • 异步：SendAsync(IAsyncCommand)/SendAsync(IAsyncCommand)
  • 输入输出：AbstractCommand/AbstractCommand<TInput,TResult>提供输入约束与执行入口
• 查询总线
  • 同步：Send(IQuery) -> query.Do()
  • 输入输出：AbstractQuery<TInput,TResult>提供输入约束与执行入口
• 设计要点
  • 命令与查询职责清晰分离，便于扩展与测试
  • 异步命令/查询通过接口约定，便于替换实现

classDiagram
class CommandBus {
+Send(ICommand)
+Send<TResult>(ICommand<TResult>) TResult
+SendAsync(IAsyncCommand) Task
+SendAsync<TResult>(IAsyncCommand<TResult>) Task<TResult>
}
class AbstractCommand~TInput~ {
+ICommand.Execute()
#OnExecute(TInput) void
}
class AbstractCommand~TInput,TResult~ {
+ICommand~TResult~.Execute() TResult
#OnExecute(TInput) TResult
}
class QueryBus {
+Send<TResult>(IQuery<TResult>) TResult
}
class AbstractQuery~TInput,TResult~ {
+Do() TResult
#OnDo(TInput) TResult
}
CommandBus --> AbstractCommand : "执行"
QueryBus --> AbstractQuery : "执行"

图表来源

• CommandBus.cs
• AbstractCommand.cs
• QueryBus.cs
• AbstractQuery.cs

章节来源

• CommandBus.cs
• AbstractCommand.cs
• QueryBus.cs
• AbstractQuery.cs

协程调度系统：CoroutineScheduler/YieldInstruction

• 协程句柄：CoroutineHandle通过实例ID与键空间分配唯一句柄，支持有效性判断
• 调度器：CoroutineScheduler维护协程槽位数组、元数据、等待关系与标签索引
• 生命周期：Run预热推进一步；Update按DeltaTime推进协程，处理等待指令与异常；Complete唤醒等待者并清理
• 等待指令：WaitForFrames等实现IYieldInstruction，支持帧等待等场景

flowchart TD
R["Run(coroutine, tag)"] --> Pre["Prewarm(推进第一步)"]
U["Update()"] --> For["遍历槽位"]
For --> Wait["等待指令 Update(delta)"]
Wait --> Done{"IsDone ?"}
Done --> |否| Skip["跳过此帧"]
Done --> |是| Move["MoveNext()"]
Move --> End{"完成 ?"}
End --> |是| Comp["Complete()<br/>唤醒等待者/清理标签/元数据"]
End --> |否| Yield["设置Waiting=当前指令"]
Comp --> For

图表来源

• CoroutineScheduler.cs
• CoroutineScheduler.cs
• CoroutineHandle.cs
• WaitForFrames.cs

章节来源

• CoroutineScheduler.cs
• CoroutineHandle.cs
• WaitForFrames.cs

依赖注入：IocContainer

• 注册策略
  • RegisterSingleton(T)：单例注册，类型唯一
  • RegisterPlurality(object)：将实例注册到其实现的所有接口与具体类型上
  • Register/Register(Type, object)：按类型注册
• 解析策略
  • Get()：返回首个实例或null
  • GetRequired()：要求唯一实例，否则抛异常
  • GetAll()：返回所有实例快照
  • GetAllSorted(Comparison)：排序后返回
• 并发与冻结
  • ReaderWriterLockSlim保证读写并发安全
  • Freeze()后禁止进一步注册，防止运行期变更

classDiagram
class IocContainer {
-ReaderWriterLockSlim _lock
-bool _frozen
-HashSet~object~ _objects
-Dictionary~Type,HashSet<object>~ _typeIndex
+RegisterSingleton<T>(T)
+RegisterPlurality(object)
+Register<T>(T)
+Register(Type, object)
+Get<T>() T?
+GetRequired<T>() T
+GetAll<T>() IReadOnlyList<T>
+GetAllSorted<T>(Comparison<T>) IReadOnlyList<T>
+Contains<T>() bool
+ContainsInstance(object) bool
+Clear()
+Freeze()
}

图表来源

• IocContainer.cs

章节来源

• IocContainer.cs

日志系统：ConsoleLoggerFactory

• 提供ILoggerFactory接口实现，创建ConsoleLogger实例
• 与Architecture集成：通过配置注入日志工厂，贯穿初始化与运行期

章节来源

• ConsoleLoggerFactory.cs

依赖分析

• 组件耦合
  • Architecture依赖ArchitectureServices与ArchitectureContext
  • ArchitectureContext依赖IocContainer与各总线接口
  • ArchitectureServices组合EventBus/CommandBus/QueryBus/AsyncQueryBus/IocContainer
  • EventBus依赖EasyEvents/EasyEvent
  • CommandBus/QueryBus独立于具体实现，通过接口解耦
• 外部依赖
  • 时间源ITimeSource用于协程调度器
  • 日志工厂通过配置注入

graph LR
Arch["Architecture"] --> Svc["ArchitectureServices"]
Arch --> Ctx["ArchitectureContext"]
Svc --> IOC["IocContainer"]
Svc --> EB["EventBus"]
Svc --> CB["CommandBus"]
Svc --> QB["QueryBus"]
EB --> EE["EasyEvents"]
EE --> Evt["EasyEvent"]
Ctx --> EB
Ctx --> CB
Ctx --> QB

图表来源

• Architecture.cs
• ArchitectureServices.cs
• EventBus.cs
• EasyEvents.cs

章节来源

• Architecture.cs
• ArchitectureServices.cs

性能考量

• 协程调度
  • 槽位数组动态扩容，避免频繁分配
  • 预热推进一步，减少首帧开销
  • 等待指令按帧更新，避免忙轮询
• 依赖注入
  • 读写锁分离读写，降低竞争
  • 冻结后禁止注册，避免运行期结构变化
• 事件系统
  • 泛型事件自动创建与缓存，减少反射成本
• 生命周期
  • 组件去重集合与顺序列表，保证初始化与销毁的确定性

故障排查指南

• 阶段转换异常
  • 现象：非法阶段转换导致异常
  • 排查：检查ArchitectureConstants的允许转换表与StrictPhaseValidation配置
• 注册时机异常
  • 现象：Ready后注册组件抛出异常
  • 排查：确认AllowLateRegistration配置或调整注册位置
• 容器冻结异常
  • 现象：冻结后仍尝试注册
  • 排查：定位冻结点，避免在Ready后注册
• 协程错误
  • 现象：协程异常被吞并或卡住
  • 排查：查看OnError处理与Complete流程，确认等待关系与标签清理
• 事件未触发
  • 现象：注册监听无效
  • 排查：确认EventBus与EasyEvents的类型键一致，监听者未被注销

章节来源

• Architecture.cs
• IocContainer.cs
• CoroutineScheduler.cs

结论

GFramework核心架构模块以清晰的职责边界与强类型契约构建，通过Architecture统一生命周期与阶段管理，结合ArchitectureContext提供统一服务门面，配合EventBus/EasyEvents实现类型安全事件，CommandBus/QueryBus落实CQRS，CoroutineScheduler提供高效协程调度，IocContainer保障依赖注入的线程安全与可演进性。整体设计强调可测试性、可扩展性与运行期稳定性。

附录

API参考与最佳实践

• Architecture
  • 初始化：Initialize/InitializeAsync；销毁：Destroy
  • 阶段：EnterPhase；钩子：RegisterLifecycleHook
  • 组件注册：RegisterSystem/RegisterModel/RegisterUtility
  • 最佳实践：在Init中完成模块安装与组件注册；避免在Ready后注册
• ArchitectureContext
  • 命令：SendCommand/SendCommandAsync
  • 查询：SendQuery/SendQueryAsync
  • 事件：SendEvent/RegisterEvent/UnRegisterEvent
  • 组件：GetSystem/GetModel/GetUtility
  • 最佳实践：优先使用Context封装的执行入口，避免直接依赖总线
• ArchitectureServices
  • 服务：Container/EventBus/CommandBus/QueryBus/AsyncQueryBus
  • 最佳实践：通过SetContext传递上下文，确保容器内组件上下文一致
• EventBus/EasyEvents/EasyEvent
  • 发送：Send()/Send(T)
  • 注册/注销：Register/UnRegister
  • 最佳实践：事件类型稳定且可序列化；避免循环引用
• CommandBus/AbstractCommand
  • 同步/异步：Send/SendAsync；带返回值版本
  • 最佳实践：命令幂等或具备补偿；输入参数实现ICommandInput
• QueryBus/AbstractQuery
  • 同步：Send
  • 最佳实践：查询无副作用；输入参数实现IQueryInput
• CoroutineScheduler/CoroutineHandle/WaitForFrames
  • 运行：Run；更新：Update；暂停/恢复/终止：Pause/Resume/Kill
  • 等待：WaitForCoroutine；按标签终止：KillByTag；清空：Clear
  • 最佳实践：合理使用标签；避免长链等待；捕获异常避免崩溃
• IocContainer
  • 注册：RegisterSingleton/RegisterPlurality/Register
  • 解析：Get/GetRequired/GetAll/GetAllSorted
  • 最佳实践：冻结前完成全部注册；避免循环依赖
• 日志
  • 最佳实践：按需设置最小级别；在关键路径打点；避免在热路径做昂贵操作