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]
17 KiB
17 KiB
模块系统
**本文档引用的文件** - [IArchitectureModule.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs) - [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs) - [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs) - [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs) - [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs) - [IArchitectureLifecycle.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureLifecycle.cs) - [IArchitecturePhaseAware.cs](file://GFramework.Core.Abstractions/architecture/IArchitecturePhaseAware.cs) - [ArchitecturePhase.cs](file://GFramework.Core.Abstractions/enums/ArchitecturePhase.cs) - [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs) - [ConsoleLoggerFactory.cs](file://GFramework.Core/logging/ConsoleLoggerFactory.cs) - [README.md（Architecture）](file://GFramework.Core/architecture/README.md) - [core-api.md](file://docs/api-reference/core-api.md) - [godot-integration.md](file://docs/tutorials/godot-integration.md)目录
简介
本文件围绕 GFramework 的模块系统展开，重点解释 InstallModule 方法的模块安装机制，涵盖模块验证、生命周期钩子注册、容器注册与模块安装调用的完整流程；阐述 IArchitectureModule 接口的设计要求与 Install 方法实现规范；说明模块安装过程中的日志记录与错误处理；解释模块系统如何支持插件化架构与动态功能扩展；介绍模块与架构生命周期的集成方式及模块对架构阶段变化的响应；最后提供模块开发的完整示例与最佳实践。
项目结构
模块系统横跨抽象层与具体实现层：
- 抽象层定义模块接口与生命周期契约，位于 Core.Abstractions；
- 具体实现包含通用模块基类（Game）、Godot 平台模块（Godot），以及核心架构（Core）负责模块安装与生命周期广播；
- 依赖注入容器（IocContainer）与日志工厂（ConsoleLoggerFactory）贯穿安装与初始化流程。
graph TB
subgraph "抽象层"
IArch["IArchitectureModule 接口"]
ILife["IArchitectureLifecycle 接口"]
IPhase["IArchitecturePhaseAware 接口"]
Phase["ArchitecturePhase 枚举"]
end
subgraph "实现层"
AbsMod["AbstractModule 抽象类"]
GodotMod["AbstractGodotModule 抽象类"]
IGodot["IGodotModule 接口"]
end
subgraph "核心"
Arch["Architecture 架构类"]
Ctnr["IocContainer 容器"]
LogFac["ConsoleLoggerFactory 日志工厂"]
end
IArch --> ILife
IArch --> IPhase
AbsMod --> IArch
GodotMod --> IGodot
IGodot --> IArch
Arch --> IArch
Arch --> Ctnr
Arch --> LogFac
Arch --> Phase
图示来源
- IArchitectureModule.cs
- AbstractModule.cs
- IGodotModule.cs
- AbstractGodotModule.cs
- Architecture.cs
- IocContainer.cs
- ConsoleLoggerFactory.cs
- ArchitecturePhase.cs
章节来源
- IArchitectureModule.cs
- AbstractModule.cs
- IGodotModule.cs
- AbstractGodotModule.cs
- Architecture.cs
- IocContainer.cs
- ConsoleLoggerFactory.cs
- ArchitecturePhase.cs
核心组件
- IArchitectureModule：模块安装的标准入口，继承生命周期与阶段感知接口，要求实现 Install 方法。
- AbstractModule：通用模块基类，提供空实现的生命周期与阶段回调，便于子类按需覆写。
- AbstractGodotModule / IGodotModule：Godot 平台模块扩展，增加节点关联、附加/分离回调与阶段感知。
- Architecture.InstallModule：模块安装主流程，负责日志记录、生命周期钩子注册、容器注册与调用模块 Install。
- IocContainer.RegisterPlurality：将模块实例注册到容器，自动注册到其实现的所有接口与具体类型。
- ArchitecturePhase：定义架构生命周期阶段，模块可通过生命周期钩子与阶段感知接口参与阶段切换。
章节来源
- IArchitectureModule.cs
- AbstractModule.cs
- IGodotModule.cs
- AbstractGodotModule.cs
- Architecture.cs
- IocContainer.cs
- ArchitecturePhase.cs
架构总览
InstallModule 的调用序列如下：
sequenceDiagram
participant Client as "调用方"
participant Arch as "Architecture"
participant Log as "日志工厂"
participant Hook as "生命周期钩子"
participant Ctnr as "IocContainer"
participant Mod as "模块(IArchitectureModule)"
Client->>Arch : "InstallModule(模块)"
Arch->>Log : "创建模块名日志记录器"
Arch->>Arch : "RegisterLifecycleHook(模块)"
Arch->>Ctnr : "RegisterPlurality(模块)"
Arch->>Mod : "Install(this)"
Arch-->>Client : "返回模块实例"
图示来源
章节来源
详细组件分析
InstallModule 方法与模块安装机制
- 模块验证：InstallModule 通过模块类型名创建日志记录器，便于追踪模块安装过程。
- 生命周期钩子注册：InstallModule 调用 RegisterLifecycleHook 将模块加入生命周期钩子列表，使其在架构阶段变化时收到通知。
- 容器注册：InstallModule 调用 Container.RegisterPlurality 将模块注册到容器，自动注册到其所有接口与具体类型，便于后续按接口获取。
- 模块安装调用：InstallModule 最终调用模块的 Install 方法，传入当前架构实例，模块在此阶段完成自身组件注册与初始化。
- 日志记录：安装开始与结束分别记录 Debug 与 Info 级别日志，便于审计与排障。
- 错误处理：InstallModule 未显式捕获异常，异常将沿调用栈向上传播，由架构初始化流程统一处理。
flowchart TD
Start(["进入 InstallModule"]) --> LogCreate["创建日志记录器"]
LogCreate --> RegHook["注册生命周期钩子"]
RegHook --> RegCtnr["容器注册模块(RegisterPlurality)"]
RegCtnr --> CallInstall["调用模块 Install(架构)"]
CallInstall --> LogDone["记录安装完成日志"]
LogDone --> End(["返回模块实例"])
图示来源
章节来源
IArchitectureModule 接口设计与 Install 方法规范
- 设计要求：IArchitectureModule 继承生命周期与阶段感知接口，确保模块能响应架构阶段变化并参与生命周期管理。
- Install 方法规范：模块应在 Install 中完成自身组件注册（系统、模型、工具等），并可读取架构上下文与服务；避免在 Install 中执行耗时或阻塞操作，建议将复杂初始化推迟到架构 Ready 阶段或异步初始化。
章节来源
生命周期钩子与阶段感知
- 生命周期钩子：模块作为 IArchitectureLifecycle 实例，在架构阶段变化时通过 OnPhase 收到通知；适合做阶段性的资源管理与性能监控。
- 阶段感知：模块作为 IArchitecturePhaseAware 实例，在架构 Ready 等关键阶段收到通知；适合做一次性初始化或收尾工作。
- 架构阶段：通过 ArchitecturePhase 枚举定义阶段，模块可在 OnArchitecturePhase 或 OnPhase 中根据阶段执行相应逻辑。
章节来源
容器注册与模块交互
- RegisterPlurality：将模块注册到容器，自动注册到其所有接口与具体类型，便于通过接口获取模块实例或其接口视图。
- 模块间交互：模块可通过架构上下文与服务与其他模块协作；也可通过事件总线进行松耦合通信。
章节来源
日志记录与错误处理
- 日志记录：InstallModule 使用日志工厂为模块创建日志记录器，安装开始与结束分别记录 Debug 与 Info 级别日志。
- 错误处理：InstallModule 未捕获异常，异常将沿调用栈向上传播；架构初始化流程会在失败时进入特定阶段并发送失败事件。
章节来源
插件化架构与动态扩展
- 模块化扩展：通过 IArchitectureModule 接口，开发者可按需实现模块并在架构初始化前或初始化后安装，实现功能的动态扩展。
- 平台集成：Godot 模块通过 IGodotModule 与 AbstractGodotModule 提供节点关联与附加/分离回调，便于与平台深度集成。
章节来源
模块与架构生命周期集成
- 阶段广播：架构在 EnterPhase 时通知所有 IArchitectureLifecycle 与 IArchitecturePhaseAware 实例，模块可据此调整自身状态。
- 严格阶段验证：可通过配置启用严格阶段验证，非法转换将抛出异常并记录致命日志。
章节来源
模块开发完整示例
- 通用模块示例：参考文档中的模块示例，展示如何实现 Install 并注册系统与工具。
- Godot 模块示例：参考文档中的 Godot 集成示例，展示节点关联、附加/分离回调与阶段响应。
章节来源
依赖分析
模块系统的关键依赖关系如下：
classDiagram
class IArchitectureModule {
+Install(architecture)
}
class IArchitectureLifecycle {
+OnPhase(phase, architecture)
}
class IArchitecturePhaseAware {
+OnArchitecturePhase(phase)
}
class AbstractModule {
+OnPhase(...)
+OnArchitecturePhase(...)
+Install(architecture)*
}
class IGodotModule {
+Node
+OnAttach(architecture)
+OnDetach()
}
class AbstractGodotModule {
+Node*
+OnAttach(...)
+OnDetach()
+Install(architecture)*
}
class Architecture {
+InstallModule(module)
+RegisterLifecycleHook(hook)
+Container
+CurrentPhase
}
class IocContainer {
+RegisterPlurality(instance)
}
class ArchitecturePhase
IArchitectureModule <|.. AbstractModule
IArchitectureModule <|.. AbstractGodotModule
IGodotModule <|.. AbstractGodotModule
IArchitectureModule --> IArchitectureLifecycle
IArchitectureModule --> IArchitecturePhaseAware
Architecture --> IArchitectureModule
Architecture --> IocContainer
Architecture --> ArchitecturePhase
图示来源
- IArchitectureModule.cs
- AbstractModule.cs
- IGodotModule.cs
- AbstractGodotModule.cs
- Architecture.cs
- IocContainer.cs
- ArchitecturePhase.cs
章节来源
- IArchitectureModule.cs
- AbstractModule.cs
- IGodotModule.cs
- AbstractGodotModule.cs
- Architecture.cs
- IocContainer.cs
- ArchitecturePhase.cs
性能考虑
- 容器冻结：架构在 Ready 阶段冻结容器，防止后续注册，确保运行期稳定性与性能。
- 异步初始化：架构支持异步初始化，模块可结合异步初始化接口提升启动性能。
- 日志级别：Debug/Info 级别日志便于开发调试，生产环境可调整日志级别降低开销。
章节来源
故障排查指南
- 模块安装失败：检查 Install 方法内是否正确注册组件；确认未在 Ready 阶段后进行注册；查看日志记录器输出定位问题。
- 生命周期钩子注册限制：生命周期钩子只能在 Ready 阶段前注册，否则会抛出异常；确认注册时机。
- 阶段转换异常：启用严格阶段验证时，非法转换会抛出异常并记录致命日志；核对阶段转换顺序。
- 销毁阶段异常：销毁流程中单个组件异常不会中断整体销毁，但会记录错误日志；逐个排查组件的 Destroy 实现。
章节来源
结论
GFramework 的模块系统通过 IArchitectureModule 接口与 Architecture.InstallModule 方法，提供了标准化的模块安装流程：先注册生命周期钩子与容器，再调用模块 Install 完成组件注册。模块可同时响应架构生命周期与阶段变化，实现插件化与动态扩展。配合严格的阶段验证、完善的日志与错误处理，模块系统在保证稳定性的同时提供了良好的可维护性与可扩展性。
附录
- 使用示例与 API 参考可参见文档：