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