mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-25 21:34:28 +08:00
a79f02c987
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件 - 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明 - 提供完整的 API 使用示例路径、最佳实践与性能建议 - 包含架构图、依赖关系图与故障排查指南 - 添加测试用例参考与扩展方法说明 - [skip ci]
22 KiB
22 KiB
架构管理系统
**本文档引用的文件** - [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs) - [ArchitectureContext.cs](file://GFramework.Core/architecture/ArchitectureContext.cs) - [GameContext.cs](file://GFramework.Core/architecture/GameContext.cs) - [ArchitectureConfiguration.cs](file://GFramework.Core/architecture/ArchitectureConfiguration.cs) - [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs) - [ArchitectureConstants.cs](file://GFramework.Core/architecture/ArchitectureConstants.cs) - [IArchitecture.cs](file://GFramework.Core.Abstractions/architecture/IArchitecture.cs) - [IArchitectureConfiguration.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureConfiguration.cs) - [IArchitectureContext.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureContext.cs) - [IArchitectureServices.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureServices.cs) - [IArchitectureModule.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs) - [IArchitectureLifecycle.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureLifecycle.cs) - [ArchitecturePhase.cs](file://GFramework.Core.Abstractions/enums/ArchitecturePhase.cs) - [README.md](file://GFramework.Core/architecture/README.md) - [SyncTestArchitecture.cs](file://GFramework.Core.Tests/architecture/SyncTestArchitecture.cs) - [AsyncTestArchitecture.cs](file://GFramework.Core.Tests/architecture/AsyncTestArchitecture.cs)目录
简介
本文件面向GFramework架构管理系统，围绕Architecture基类的设计与实现展开，系统性阐述其作为系统、模型、工具等组件的注册与管理中心，生命周期管理机制（阶段转换、初始化流程控制、销毁过程），组件注册体系（RegisterSystem、RegisterModel、RegisterUtility等），模块安装机制（InstallModule）与插件化架构，架构上下文（ArchitectureContext）与GameContext绑定机制，以及架构配置（IArchitectureConfiguration）与架构服务（IArchitectureServices）的使用范式。同时提供架构初始化的完整流程图与最佳实践建议。
项目结构
GFramework.Core的architecture目录为核心实现区域，包含架构基类、上下文、服务、配置与常量等关键文件；Abstractions目录提供接口契约；Tests目录包含使用示例与测试架构；README.md提供使用说明与最佳实践。
graph TB
subgraph "核心实现"
A["Architecture.cs"]
ACtx["ArchitectureContext.cs"]
GCtx["GameContext.cs"]
Conf["ArchitectureConfiguration.cs"]
Svc["ArchitectureServices.cs"]
Const["ArchitectureConstants.cs"]
end
subgraph "抽象接口"
IA["IArchitecture.cs"]
IConf["IArchitectureConfiguration.cs"]
ICtx["IArchitectureContext.cs"]
ISvc["IArchitectureServices.cs"]
IM["IArchitectureModule.cs"]
IL["IArchitectureLifecycle.cs"]
AP["ArchitecturePhase.cs"]
end
subgraph "测试与文档"
R["README.md"]
STA["SyncTestArchitecture.cs"]
ATA["AsyncTestArchitecture.cs"]
end
A --> IA
ACtx --> ICtx
Svc --> ISvc
Conf --> IConf
Const --> AP
A --> Svc
A --> ACtx
A --> Const
A --> Conf
GCtx --> ACtx
IM --> IL
图表来源
- Architecture.cs
- ArchitectureContext.cs
- GameContext.cs
- ArchitectureConfiguration.cs
- ArchitectureServices.cs
- ArchitectureConstants.cs
- IArchitecture.cs
- IArchitectureConfiguration.cs
- IArchitectureContext.cs
- IArchitectureServices.cs
- IArchitectureModule.cs
- IArchitectureLifecycle.cs
- ArchitecturePhase.cs
- README.md
- SyncTestArchitecture.cs
- AsyncTestArchitecture.cs
章节来源
核心组件
- Architecture基类：实现IArchitecture，负责生命周期管理、初始化流程控制、阶段转换、组件注册与销毁、模块安装与生命周期钩子管理。
- ArchitectureContext：实现IArchitectureContext，提供服务获取、命令/查询/事件执行、系统/模型/工具获取、环境访问等。
- GameContext：静态管理器，维护架构类型到架构上下文的绑定映射。
- ArchitectureServices：实现IArchitectureServices，提供IoC容器、事件总线、命令/查询总线等核心服务。
- ArchitectureConfiguration：实现IArchitectureConfiguration，提供日志与架构行为配置。
- ArchitectureConstants：定义阶段顺序与允许的阶段转换关系。
- 架构阶段枚举：ArchitecturePhase定义完整的生命周期阶段序列。
章节来源
- Architecture.cs
- ArchitectureContext.cs
- GameContext.cs
- ArchitectureServices.cs
- ArchitectureConfiguration.cs
- ArchitectureConstants.cs
- ArchitecturePhase.cs
架构总览
下图展示Architecture基类与其依赖的上下文、服务、配置、常量之间的交互关系，以及模块安装与生命周期钩子的集成点。
classDiagram
class Architecture {
+Initialize()
+InitializeAsync()
+Destroy()
+RegisterSystem(system)
+RegisterModel(model)
+RegisterUtility(utility)
+InstallModule(module)
+RegisterLifecycleHook(hook)
+CurrentPhase
+Context
}
class ArchitectureContext {
+GetService<T>()
+GetSystem<T>()
+GetModel<T>()
+GetUtility<T>()
+SendCommand(...)
+SendQuery<TResult>(...)
+SendEvent<T>(...)
+RegisterEvent<T>(...)
+GetEnvironment()
}
class GameContext {
+Bind(architectureType, context)
+Get<T>()
+TryGet<T>(out)
+GetByType(type)
+GetFirstArchitectureContext()
+Unbind(architectureType)
+Clear()
}
class ArchitectureServices {
+Container
+EventBus
+CommandBus
+QueryBus
+AsyncQueryBus
+SetContext(context)
+GetContext()
}
class ArchitectureConfiguration {
+LoggerProperties
+ArchitectureProperties
}
class ArchitectureConstants {
+PhaseOrder
+PhaseTransitions
}
class IArchitecture
class IArchitectureContext
class IArchitectureServices
class IArchitectureConfiguration
class IArchitectureModule
class IArchitectureLifecycle
class ArchitecturePhase
Architecture ..|> IArchitecture
ArchitectureContext ..|> IArchitectureContext
ArchitectureServices ..|> IArchitectureServices
ArchitectureConfiguration ..|> IArchitectureConfiguration
Architecture --> ArchitectureContext : "使用"
Architecture --> ArchitectureServices : "使用"
Architecture --> ArchitectureConfiguration : "使用"
Architecture --> ArchitectureConstants : "使用"
Architecture --> GameContext : "绑定"
IArchitectureModule <|-- IArchitectureLifecycle
ArchitecturePhase <.. ArchitectureConstants
图表来源
- Architecture.cs
- ArchitectureContext.cs
- GameContext.cs
- ArchitectureServices.cs
- ArchitectureConfiguration.cs
- ArchitectureConstants.cs
- IArchitecture.cs
- IArchitectureContext.cs
- IArchitectureServices.cs
- IArchitectureConfiguration.cs
- IArchitectureModule.cs
- IArchitectureLifecycle.cs
- ArchitecturePhase.cs
详细组件分析
Architecture基类：生命周期与初始化流程
- 阶段管理
- EnterPhase负责阶段转换校验、状态更新、事件通知与阶段感知对象通知。
- ValidatePhaseTransition根据ArchitectureConstants的允许转换表与配置项StrictPhaseValidation进行校验。
- NotifyPhase与NotifyPhaseAwareObjects分别通知生命周期钩子与IArchitecturePhaseAware对象。
- 组件注册与生命周期
- RegisterLifecycleComponent统一处理IInitializable与IDisposable组件的登记与去重，保证初始化顺序与逆序销毁。
- RegisterSystem/RegisterModel/RegisterUtility在注册时设置上下文、登记生命周期并写入容器。
- 初始化流程
- Initialize/InitializeAsync封装InitializeInternalAsync，负责日志工厂设置、环境初始化、上下文创建与绑定、调用子类Init、组件分阶段初始化、容器冻结、进入Ready并发布事件。
- InitializeAllComponentsAsync按工具、模型、系统三阶段顺序初始化，支持同步与异步组件。
- 销毁流程
- Destroy进入Destroying阶段并发布事件，按逆序销毁IDisposable组件，最后进入Destroyed并发布事件。
- 模块安装
- InstallModule安装IArchitectureModule，注册生命周期钩子、登记模块实例、调用Install以完成模块内组件注册。
sequenceDiagram
participant Client as "调用方"
participant Arch as "Architecture"
participant Ctx as "ArchitectureContext"
participant Svc as "ArchitectureServices"
participant Bus as "EventBus"
participant C as "IoC容器"
Client->>Arch : "Initialize()/InitializeAsync()"
Arch->>Svc : "设置日志工厂/环境初始化"
Arch->>Ctx : "创建上下文并绑定"
Arch->>Arch : "调用子类Init()"
Arch->>Arch : "InitializeAllComponentsAsync()"
Arch->>C : "冻结容器"
Arch->>Bus : "发送Ready事件"
Arch-->>Client : "完成初始化"
图表来源
章节来源
ArchitectureContext：上下文服务与组件访问
- 服务缓存：通过私有字典缓存已解析的服务实例，减少容器查询开销。
- 组件获取：GetService/GetSystem/GetModel/GetUtility提供类型化服务解析。
- 命令/查询/事件：封装CommandBus、QueryBus、EventBus的发送与注册。
- 环境访问：GetEnvironment返回已注册的环境实例。
flowchart TD
Start(["进入上下文方法"]) --> CheckCache["检查服务缓存"]
CheckCache --> CacheHit{"命中缓存？"}
CacheHit --> |是| ReturnCached["返回缓存实例"]
CacheHit --> |否| Resolve["从容器解析服务"]
Resolve --> Found{"解析成功？"}
Found --> |是| Cache["写入缓存"]
Cache --> ReturnResolved["返回解析实例"]
Found --> |否| ThrowErr["抛出未注册异常"]
ReturnCached --> End(["结束"])
ReturnResolved --> End
ThrowErr --> End
图表来源
章节来源
GameContext：架构上下文绑定与管理
- 绑定：Bind将架构类型与上下文实例建立唯一映射，防止重复绑定。
- 获取：Get/Get/TryGet提供强类型与泛型安全的上下文访问。
- 字典：使用并发字典保证多线程场景下的安全性。
- 清理：Unbind/Clear支持解除绑定与清空。
flowchart TD
A["Bind(architectureType, context)"] --> Check["尝试添加键值对"]
Check --> Added{"添加成功？"}
Added --> |是| Done["绑定完成"]
Added --> |否| ThrowDup["抛出重复绑定异常"]
B["Get<T>()"] --> Lookup["按类型查找"]
Lookup --> Found{"找到？"}
Found --> |是| Return["返回上下文实例"]
Found --> |否| ThrowNotFound["抛出未找到异常"]
图表来源
章节来源
ArchitectureServices：核心服务聚合
- 容器与总线：提供IoC容器、事件总线、命令总线、查询总线与异步查询总线。
- 上下文设置：SetContext将架构上下文传递给容器与自身，确保服务可用。
- 注册：在构造函数中将核心服务注册到容器，供上下文解析。
章节来源
ArchitectureConfiguration：配置与策略
- 日志配置：LoggerProperties包含日志工厂提供程序与最小日志级别。
- 架构选项：ArchitectureProperties包含AllowLateRegistration与StrictPhaseValidation等策略开关。
章节来源
ArchitectureConstants：阶段与转换规则
- 阶段顺序：PhaseOrder定义线性阶段序列。
- 转换规则：PhaseTransitions定义允许的阶段转换集合，支持从任意阶段转入FailedInitialization。
章节来源
接口契约与模块化
- IArchitecture：定义初始化、销毁、组件注册、模块安装与生命周期钩子注册。
- IArchitectureContext：定义服务获取、命令/查询/事件执行与环境访问。
- IArchitectureServices：定义容器与核心总线服务。
- IArchitectureModule：模块安装接口，继承生命周期与阶段感知。
- IArchitectureLifecycle：阶段回调接口。
- ArchitecturePhase：阶段枚举。
章节来源
- IArchitecture.cs
- IArchitectureContext.cs
- IArchitectureServices.cs
- IArchitectureModule.cs
- IArchitectureLifecycle.cs
- ArchitecturePhase.cs
测试架构示例：使用模式
- 同步测试架构：在Init中注册同步模型与系统，演示标准注册流程。
- 异步测试架构：在Init中注册异步模型与系统，演示异步初始化流程。
章节来源
依赖关系分析
- Architecture对IArchitectureConfiguration、IArchitectureServices、IArchitectureContext、ArchitectureConstants、ArchitecturePhase的依赖清晰且稳定。
- ArchitectureContext依赖IArchitectureServices与IArchitectureContext接口，通过容器解析核心服务。
- GameContext独立于架构实现，仅持有IArchitectureContext实例，提供全局绑定管理。
- 模块与生命周期钩子通过IArchitectureModule与IArchitectureLifecycle接入，增强扩展性。
graph LR
Arch["Architecture"] --> Conf["IArchitectureConfiguration"]
Arch --> Svc["IArchitectureServices"]
Arch --> Ctx["IArchitectureContext"]
Arch --> Const["ArchitectureConstants"]
Arch --> Phase["ArchitecturePhase"]
Ctx --> Svc
GCtx["GameContext"] --> Ctx
Mod["IArchitectureModule"] --> Life["IArchitectureLifecycle"]
图表来源
- Architecture.cs
- ArchitectureContext.cs
- GameContext.cs
- IArchitectureModule.cs
- IArchitectureLifecycle.cs
章节来源
性能考虑
- 服务缓存：ArchitectureContext对服务解析结果进行缓存，降低容器查询成本。
- 去重与顺序：Architecture使用HashSet与List双重结构管理待初始化与可销毁组件，确保原子去重与确定性顺序。
- 异步初始化：支持IAsyncInitializable与IAsyncQuery，充分利用异步I/O提升初始化吞吐。
- 容器冻结：初始化完成后冻结IoC容器，避免后续注册带来的性能与一致性问题。
故障排查指南
- 初始化失败
- 现象：Initialize/InitializeAsync抛出异常后进入FailedInitialization阶段并发布失败事件。
- 排查：检查Init中注册的组件是否正确实现接口、依赖是否已注册、日志级别是否足够详细。
- 阶段转换异常
- 现象：ValidatePhaseTransition抛出非法转换异常。
- 排查：确认当前阶段与允许转换表，必要时调整StrictPhaseValidation策略。
- 组件注册时机
- 现象：在Ready阶段后注册组件抛出异常。
- 排查：通过AllowLateRegistration策略控制注册窗口，或在Init中集中注册。
- 销毁异常
- 现象：销毁过程中某个组件抛出异常但不影响其他组件。
- 排查：捕获异常并记录日志，确保资源清理的幂等性。
章节来源
结论
Architecture基类通过明确的阶段化生命周期、严格的注册时机控制、统一的组件注册与销毁机制，以及模块化与上下文绑定设计，构建了高内聚、低耦合、可扩展的架构管理体系。结合ArchitectureContext与GameContext提供的全局绑定与服务访问，开发者可以以一致的方式组织系统、模型与工具组件，并通过IArchitectureConfiguration与IArchitectureServices灵活定制行为与服务。
附录
架构初始化完整流程图
flowchart TD
Start(["开始 Initialize/InitializeAsync"]) --> Setup["设置日志工厂/初始化环境"]
Setup --> Ctx["创建并绑定架构上下文"]
Ctx --> UserInit["调用子类 Init()"]
UserInit --> CompInit["InitializeAllComponentsAsync()"]
CompInit --> PhaseU1["BeforeUtilityInit"]
PhaseU1 --> UInit["初始化工具组件"]
UInit --> PhaseU2["AfterUtilityInit"]
PhaseU2 --> PhaseM1["BeforeModelInit"]
PhaseM1 --> MInit["初始化模型组件"]
MInit --> PhaseM2["AfterModelInit"]
PhaseM2 --> PhaseS1["BeforeSystemInit"]
PhaseS1 --> SInit["初始化系统组件"]
SInit --> PhaseS2["AfterSystemInit"]
PhaseS2 --> Freeze["冻结IoC容器"]
Freeze --> Ready["进入 Ready 阶段并发布事件"]
Ready --> End(["初始化完成"])
Fail(["初始化异常"]) --> FailPhase["进入 FailedInitialization 并发布事件"]
Fail --> End
图表来源
最佳实践建议
- 在Init中集中注册组件，避免在Ready后注册导致异常。
- 合理划分Utility/Model/System职责边界，遵循“数据/状态”、“业务逻辑/规则”、“无状态工具”的分层原则。
- 使用模块化（InstallModule）扩展架构功能，保持核心简洁。
- 通过IArchitectureConfiguration定制日志与阶段验证策略，满足不同部署需求。
- 使用ArchitectureContext进行服务访问，避免直接依赖具体实现。
- 对可能耗时的初始化使用异步组件，提升整体启动性能。
章节来源