# 模块化架构 **本文档引用的文件** - [GFramework.Core.csproj](file://GFramework.Core/GFramework.Core.csproj) - [GFramework.Core.Abstractions.csproj](file://GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj) - [GFramework.Game.csproj](file://GFramework.Game/GFramework.Game.csproj) - [GFramework.Game.Abstractions.csproj](file://GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj) - [GFramework.Godot.csproj](file://GFramework.Godot/GFramework.Godot.csproj) - [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj) - [架构.cs](file://GFramework.Core/architecture/Architecture.cs) - [架构配置.cs](file://GFramework.Core/architecture/ArchitectureConfiguration.cs) - [游戏上下文.cs](file://GFramework.Core/architecture/GameContext.cs) - [模块接口.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs) - [抽象模块.cs](file://GFramework.Game/architecture/AbstractModule.cs) - [抽象Godot模块.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs) - [IGodot模块.cs](file://GFramework.Godot/architecture/IGodotModule.cs) - [事件总线.cs](file://GFramework.Core/events/EventBus.cs) - [简单事件.cs](file://GFramework.Core/events/EasyEvent.cs) - [设置系统.cs](file://GFramework.Game/setting/SettingsSystem.cs) - [UI路由器基类.cs](file://GFramework.Game/ui/UiRouterBase.cs) ## 目录 1. [引言](#引言) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构总览](#架构总览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [性能考量](#性能考量) 8. [故障排查指南](#故障排查指南) 9. [结论](#结论) 10. [附录](#附录) ## 引言 本文件面向GFramework的模块化架构，系统性阐述模块边界设计、安装与卸载流程、模块内系统与工具的组织方式、模块间通过事件的松耦合通信模式，以及模块化架构的测试策略与维护建议。文档旨在帮助开发者在不牺牲可扩展性与可维护性的前提下，快速搭建稳定可靠的模块化系统。 ## 项目结构 GFramework采用多项目分层与模块化组合的方式： - 核心层：提供架构基座、生命周期管理、事件系统、IoC容器等通用能力 - 游戏层：在核心之上提供游戏域的系统与工具（如设置系统、UI路由器） - 平台适配层：针对Godot平台提供模块与节点绑定能力 - 抽象层：定义跨层接口契约，确保模块边界清晰、可替换 ```mermaid graph TB subgraph "核心层" Core["GFramework.Core
架构/事件/IoC/系统/模型/工具"] CoreAbst["GFramework.Core.Abstractions
接口契约"] end subgraph "游戏层" Game["GFramework.Game
设置系统/UI路由器"] GameAbst["GFramework.Game.Abstractions
游戏域接口"] end subgraph "平台层" Godot["GFramework.Godot
Godot模块/节点/日志/场景注册"] Gen["GFramework.Godot.SourceGenerators
源生成器"] end CoreAbst --> Core GameAbst --> Game Core --> Game Game --> Godot CoreAbst --> Godot GameAbst --> Godot Gen --> Godot ``` 图表来源 - [GFramework.Core.csproj](file://GFramework.Core/GFramework.Core.csproj#L1-L13) - [GFramework.Core.Abstractions.csproj](file://GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj#L1-L29) - [GFramework.Game.csproj](file://GFramework.Game/GFramework.Game.csproj#L1-L17) - [GFramework.Game.Abstractions.csproj](file://GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj#L1-L31) - [GFramework.Godot.csproj](file://GFramework.Godot/GFramework.Godot.csproj#L1-L22) - [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L1-L71) 章节来源 - [GFramework.Core.csproj](file://GFramework.Core/GFramework.Core.csproj#L1-L13) - [GFramework.Core.Abstractions.csproj](file://GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj#L1-L29) - [GFramework.Game.csproj](file://GFramework.Game/GFramework.Game.csproj#L1-L17) - [GFramework.Game.Abstractions.csproj](file://GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj#L1-L31) - [GFramework.Godot.csproj](file://GFramework.Godot/GFramework.Godot.csproj#L1-L22) - [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L1-L71) ## 核心组件 - 架构基座：统一管理模块安装、组件注册、生命周期与阶段转换 - 模块接口与抽象：定义模块安装协议与阶段感知能力 - 事件系统：提供类型化事件总线，支持模块间松耦合通信 - 游戏域系统：设置系统、UI路由器等具体业务模块 章节来源 - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L38-L48) - [模块接口.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs#L1-L14) - [抽象模块.cs](file://GFramework.Game/architecture/AbstractModule.cs#L9-L33) - [事件总线.cs](file://GFramework.Core/events/EventBus.cs#L8-L55) - [设置系统.cs](file://GFramework.Game/setting/SettingsSystem.cs#L11-L99) - [UI路由器基类.cs](file://GFramework.Game/ui/UiRouterBase.cs#L13-L725) ## 架构总览 模块化架构围绕“架构基座 + 模块 + 系统/工具”的层次展开。模块通过Install接入架构，注册自身系统与工具，参与架构生命周期与阶段转换；模块间通过事件总线进行解耦通信。 ```mermaid classDiagram class 架构基座 { +InstallModule(module) +RegisterSystem(system) +RegisterModel(model) +RegisterUtility(utility) +Initialize()/InitializeAsync() +Destroy() +EnterPhase(phase) } class 模块接口 { <> +Install(架构) +OnPhase(...) +OnArchitecturePhase(...) } class 抽象模块 { +Install(架构) +OnPhase(...) +OnArchitecturePhase(...) } class 事件总线 { +Send() +Register(handler) +UnRegister(handler) } class 设置系统 { +ApplyAll() +Apply() +Apply(type) } class UI路由器基类 { +Push(key,...) +Pop(policy) +Replace(key,...) +Clear() +RegisterHandler(...) +UnregisterHandler(...) } 模块接口 <|.. 抽象模块 架构基座 --> 模块接口 : "InstallModule()" 架构基座 --> 事件总线 : "使用" 设置系统 ..|> 系统接口 UI路由器基类 ..|> 系统接口 设置系统 --> 事件总线 : "发送设置事件" UI路由器基类 --> 事件总线 : "发送UI切换事件" ``` 图表来源 - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L38-L48) - [模块接口.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs#L1-L14) - [抽象模块.cs](file://GFramework.Game/architecture/AbstractModule.cs#L9-L33) - [事件总线.cs](file://GFramework.Core/events/EventBus.cs#L8-L55) - [设置系统.cs](file://GFramework.Game/setting/SettingsSystem.cs#L11-L99) - [UI路由器基类.cs](file://GFramework.Game/ui/UiRouterBase.cs#L13-L725) ## 详细组件分析 ### 模块边界与设计原则 - 边界清晰：模块通过IArchitectureModule定义安装入口与阶段感知，避免跨模块直接耦合 - 单一职责：每个模块聚焦于特定领域（如设置、UI、音频等），内部聚合相关系统与工具 - 可替换性：模块依赖接口而非具体实现，便于在不同平台或场景下替换 - 可观测性：模块安装与阶段变化均通过日志记录，便于问题定位 章节来源 - [模块接口.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs#L1-L14) - [抽象模块.cs](file://GFramework.Game/architecture/AbstractModule.cs#L9-L33) - [抽象Godot模块.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L11-L55) - [IGodot模块.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L10-L27) ### 模块安装与卸载流程 - 安装流程：架构调用InstallModule注册生命周期钩子、将模块注册到IoC容器并执行模块Install - 卸载流程：通过架构Destroy触发销毁阶段，按注册逆序调用IDisposable组件的Destroy ```mermaid sequenceDiagram participant App as "应用" participant Arch as "架构基座" participant Mod as "模块" participant Ctn as "IoC容器" participant Bus as "事件总线" App->>Arch : "InstallModule(模块)" Arch->>Arch : "RegisterLifecycleHook(模块)" Arch->>Ctn : "RegisterPlurality(模块)" Arch->>Mod : "Install(架构)" Arch->>Bus : "发送就绪事件(可选)" App->>Arch : "Destroy()" Arch->>Arch : "EnterPhase(Destroying)" Arch->>Bus : "发送销毁中事件" loop 逆序销毁 Arch->>Mod : "Destroy()" end Arch->>Arch : "EnterPhase(Destroyed)" Arch->>Bus : "发送已销毁事件" ``` 图表来源 - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L38-L48) - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L357-L396) 章节来源 - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L38-L48) - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L357-L396) ### 模块内系统与工具组织 - 系统注册：架构提供RegisterSystem/RegisterModel/RegisterUtility，统一设置上下文、注册生命周期并按阶段初始化 - 初始化阶段：工具 → 模型 → 系统，阶段间可插入自定义逻辑 - 上下文绑定：GameContext提供多架构上下文绑定与查询，便于跨模块访问 ```mermaid flowchart TD Start(["模块Install"]) --> RegSys["注册系统/模型/工具"] RegSys --> SetCtx["设置上下文"] SetCtx --> RegLC["注册生命周期组件"] RegLC --> PhaseTools["进入工具初始化阶段"] PhaseTools --> InitTools["初始化工具"] InitTools --> PhaseModels["进入模型初始化阶段"] PhaseModels --> InitModels["初始化模型"] InitModels --> PhaseSystems["进入系统初始化阶段"] PhaseSystems --> InitSystems["初始化系统"] InitSystems --> Freeze["冻结IoC容器"] Freeze --> Ready["进入Ready阶段"] ``` 图表来源 - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L423-L460) - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L264-L330) - [游戏上下文.cs](file://GFramework.Core/architecture/GameContext.cs#L9-L111) 章节来源 - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L423-L460) - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L264-L330) - [游戏上下文.cs](file://GFramework.Core/architecture/GameContext.cs#L9-L111) ### 模块间通信：事件驱动的松耦合 - 类型化事件：EventBus提供基于类型的Send/Register/UnRegister，模块通过事件发布/订阅实现解耦 - 典型场景：设置系统在应用设置前后发送事件；UI路由器在页面切换前后发送事件 ```mermaid sequenceDiagram participant ModA as "模块A" participant Bus as "事件总线" participant ModB as "模块B" ModA->>Bus : "Send(事件A)" Bus-->>ModB : "触发监听器" ModB-->>Bus : "UnRegister(监听器)" ``` 图表来源 - [事件总线.cs](file://GFramework.Core/events/EventBus.cs#L8-L55) - [简单事件.cs](file://GFramework.Core/events/EasyEvent.cs#L8-L39) - [设置系统.cs](file://GFramework.Game/setting/SettingsSystem.cs#L86-L98) - [UI路由器基类.cs](file://GFramework.Game/ui/UiRouterBase.cs#L339-L364) 章节来源 - [事件总线.cs](file://GFramework.Core/events/EventBus.cs#L8-L55) - [简单事件.cs](file://GFramework.Core/events/EasyEvent.cs#L8-L39) - [设置系统.cs](file://GFramework.Game/setting/SettingsSystem.cs#L86-L98) - [UI路由器基类.cs](file://GFramework.Game/ui/UiRouterBase.cs#L339-L364) ### 具体模块示例：设置模块与UI模块 - 设置模块（SettingsSystem） - 负责批量/按类型应用设置，发送应用前/后事件，捕获异常并上报 - UI模块（UiRouterBase） - 提供页面栈管理、层级管理、路由守卫、UI切换处理器管道与事件 章节来源 - [设置系统.cs](file://GFramework.Game/setting/SettingsSystem.cs#L11-L99) - [UI路由器基类.cs](file://GFramework.Game/ui/UiRouterBase.cs#L13-L725) ## 依赖关系分析 - 核心层依赖抽象层，保证接口稳定 - 游戏层依赖核心层与抽象层，提供业务系统 - 平台层依赖核心与游戏抽象层，提供平台适配 - 源生成器作为编译期工具，不引入运行时依赖 ```mermaid graph LR CoreAbst["Core.Abstractions"] --> Core["Core"] GameAbst["Game.Abstractions"] --> Game["Game"] CoreAbst --> Godot["Godot"] GameAbst --> Godot Core --> Game CoreAbst --> GameAbst Gen["Godot.SourceGenerators"] --> Godot ``` 图表来源 - [GFramework.Core.csproj](file://GFramework.Core/GFramework.Core.csproj#L9-L12) - [GFramework.Game.csproj](file://GFramework.Game/GFramework.Game.csproj#L9-L12) - [GFramework.Godot.csproj](file://GFramework.Godot/GFramework.Godot.csproj#L16-L20) - [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L30-L33) 章节来源 - [GFramework.Core.csproj](file://GFramework.Core/GFramework.Core.csproj#L9-L12) - [GFramework.Game.csproj](file://GFramework.Game/GFramework.Game.csproj#L9-L12) - [GFramework.Godot.csproj](file://GFramework.Godot/GFramework.Godot.csproj#L16-L20) - [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L30-L33) ## 性能考量 - 初始化阶段分层：工具/模型/系统分阶段初始化，有利于资源占用与启动时间控制 - 生命周期去重：注册去重集合避免重复初始化与销毁 - 事件总线：类型化事件减少反射开销，支持异步处理 - UI切换：前置与后置阶段分离，避免阻塞主线程 章节来源 - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L264-L330) - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L229-L258) - [UI路由器基类.cs](file://GFramework.Game/ui/UiRouterBase.cs#L339-L364) ## 故障排查指南 - 阶段转换异常：检查架构配置的严格阶段校验与允许的阶段转换表 - 注册时机错误：在Ready之后仍尝试注册组件会抛出异常，需在Install或BeforeReady阶段完成 - 销毁异常：单个组件销毁异常不会影响整体销毁流程，但会记录错误日志 - 事件未触发：确认事件监听器已注册且事件类型一致 章节来源 - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L164-L183) - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L407-L414) - [架构.cs](file://GFramework.Core/architecture/Architecture.cs#L377-L387) - [事件总线.cs](file://GFramework.Core/events/EventBus.cs#L41-L54) ## 结论 GFramework的模块化架构通过清晰的模块边界、统一的生命周期管理与事件驱动的通信机制，实现了高内聚、低耦合的系统设计。遵循本文的最佳实践，可在复杂项目中保持模块的独立性与演进速度，同时降低集成风险。 ## 附录 - 测试策略建议 - 模块独立测试：对模块内的系统与工具进行单元测试，模拟Install与Initialize流程 - 集成测试：通过Mock事件总线与IoC容器，验证模块间事件交互与阶段流转 - 平台适配测试：在Godot环境下验证模块的节点绑定与生命周期钩子 - 维护建议 - 严格遵守模块边界，避免跨模块直接依赖 - 通过事件总线传递消息，减少硬编码耦合 - 定期重构：拆分过大的模块，提炼公共工具与系统 - 文档与契约：保持抽象层接口稳定，逐步演进实现层