# 模块化设计

<cite>
**本文引用的文件**
- [README.md](file://GFramework.Core/README.md)
- [README.md](file://GFramework.Core.Abstractions/README.md)
- [README.md](file://GFramework.Game/README.md)
- [README.md](file://GFramework.Godot/README.md)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs)
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs)
- [IArchitectureModule.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs)
- [BindableProperty.cs](file://GFramework.Core/property/BindableProperty.cs)
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs)
- [SettingsModel.cs](file://GFramework.Game/setting/SettingsModel.cs)
</cite>

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

## 简介
本教程围绕 GFramework 的模块化设计展开，系统讲解模块化架构的设计原则与实现策略，包括关注点分离、依赖注入、接口抽象、事件驱动与生命周期管理等核心概念。教程将结合 GFramework.Core、GFramework.Core.Abstractions、GFramework.Game、GFramework.Godot 等模块，给出可复用的模块组件设计思路、模块间解耦策略、模块生命周期管理方法，并说明在大型游戏项目中的应用实践，涵盖功能模块划分、协作模式与版本兼容性管理。最后提供最佳实践与常见问题的解决方案。

## 项目结构
GFramework 采用分层与模块化相结合的组织方式：
- GFramework.Core：平台无关的核心框架，提供架构、IoC、事件、命令/查询、属性绑定、状态机等通用能力。
- GFramework.Core.Abstractions：核心抽象契约，定义接口、枚举与配置，确保可移植性与可替换性。
- GFramework.Game：游戏特定功能模块，提供设置、存储、序列化、UI 路由等游戏开发常用能力，并内置模块化架构。
- GFramework.Godot：Godot 平台集成模块，提供节点扩展、信号桥接、节点池化、日志集成等能力，与核心框架深度结合。

```mermaid
graph TB
subgraph "核心层"
Core["GFramework.Core<br/>架构/事件/IoC/命令/查询/属性/状态机"]
Abstractions["GFramework.Core.Abstractions<br/>接口/枚举/配置"]
end
subgraph "游戏层"
Game["GFramework.Game<br/>设置/存储/序列化/UI路由/模块化架构"]
GameAbstractions["GFramework.Game.Abstractions<br/>游戏抽象接口"]
end
subgraph "平台层"
Godot["GFramework.Godot<br/>节点扩展/信号/池化/日志集成"]
SourceGen["GFramework.SourceGenerators<br/>上下文感知/日志生成器"]
end
Abstractions --> Core
Core --> Game
GameAbstractions --> Game
Core --> Godot
SourceGen --> Godot
```

图表来源
- [README.md](file://GFramework.Core/README.md#L16-L508)
- [README.md](file://GFramework.Core.Abstractions/README.md#L1-L522)
- [README.md](file://GFramework.Game/README.md#L1-L1402)
- [README.md](file://GFramework.Godot/README.md#L1-L893)

章节来源
- [README.md](file://GFramework.Core/README.md#L16-L508)
- [README.md](file://GFramework.Core.Abstractions/README.md#L1-L522)
- [README.md](file://GFramework.Game/README.md#L1-L1402)
- [README.md](file://GFramework.Godot/README.md#L1-L893)

## 核心组件
- 架构与生命周期：通过 Architecture 管理组件注册、初始化阶段与销毁流程，支持模块安装与阶段感知。
- IoC 容器：IocContainer 提供注册、解析、冻结与多实例管理，支撑依赖注入与组件解耦。
- 事件系统：EventBus 提供类型事件的发送、注册与注销，实现跨层松耦合通信。
- 模块化架构：AbstractModule 与 IArchitectureModule 定义模块安装与阶段回调，支持模块化功能拆分与生命周期管理。
- 命令/查询：AbstractCommand/AbstractQuery 封装写/读操作，配合总线实现职责分离。
- 属性绑定：BindableProperty 支持数据变化通知，简化 UI 与模型的响应式绑定。
- 状态机：StateMachine 管理状态注册、切换与历史，支持状态驱动的模块行为。
- 设置模型：SettingsModel 管理设置数据与可应用设置，支持模块化配置与版本兼容。

章节来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs#L1-L55)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L1-L33)
- [IArchitectureModule.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs#L1-L14)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L1-L53)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L1-L29)
- [BindableProperty.cs](file://GFramework.Core/property/BindableProperty.cs#L1-L135)
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs#L1-L276)
- [SettingsModel.cs](file://GFramework.Game/setting/SettingsModel.cs#L1-L103)

## 架构总览
GFramework 的模块化架构以 Architecture 为核心，通过 IoC 容器管理组件生命周期，借助事件系统实现跨层通信，模块通过 IArchitectureModule 接口安装到架构并在不同阶段执行逻辑。游戏层与平台层在此基础上扩展出设置、存储、序列化、UI 路由与 Godot 集成等能力。

```mermaid
classDiagram
class Architecture {
+InstallModule(module)
+RegisterSystem(system)
+RegisterModel(model)
+RegisterUtility(utility)
+Initialize()
+Destroy()
+CurrentPhase
}
class IArchitectureModule {
+Install(architecture)
+OnArchitecturePhase(phase)
}
class AbstractModule {
+Install(architecture)
+OnArchitecturePhase(phase)
}
class IocContainer {
+RegisterPlurality(instance)
+RegisterSingleton(instance)
+Get<T>()
+GetAll<T>()
+Freeze()
}
class EventBus {
+Send<T>()
+Register<T>(handler)
+UnRegister<T>(handler)
}
class AbstractCommand {
+Execute()
#OnExecute(input)
}
class AbstractQuery {
+Do()
#OnDo(input)
}
class BindableProperty {
+Value
+Register(handler)
+RegisterWithInitValue(handler)
+UnRegister(handler)
}
class StateMachine {
+Register(state)
+ChangeTo<T>()
+GoBack()
+GetState<T>()
}
class SettingsModel {
+GetData<T>()
+RegisterApplicator(applicator)
+GetApplicator<T>()
+All()
}
AbstractModule ..|> IArchitectureModule
Architecture --> IArchitectureModule : "安装/阶段通知"
Architecture --> IocContainer : "依赖注入"
Architecture --> EventBus : "事件总线"
AbstractCommand --> Architecture : "上下文访问"
AbstractQuery --> Architecture : "上下文访问"
BindableProperty --> EventBus : "事件回调"
StateMachine --> IState : "状态管理"
SettingsModel --> ISettingsData : "数据节"
SettingsModel --> IApplyAbleSettings : "应用器"
```

图表来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs#L1-L55)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L1-L33)
- [IArchitectureModule.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs#L1-L14)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L1-L53)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L1-L29)
- [BindableProperty.cs](file://GFramework.Core/property/BindableProperty.cs#L1-L135)
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs#L1-L276)
- [SettingsModel.cs](file://GFramework.Game/setting/SettingsModel.cs#L1-L103)

## 详细组件分析

### 模块化架构与生命周期
- 模块安装：通过 Architecture.InstallModule 注册模块、注册生命周期钩子、调用模块 Install 并记录日志。
- 阶段感知：模块实现 IArchitecturePhaseAware，在架构不同阶段（如 BeforeUtilityInit、AfterModelInit、Ready、Destroying 等）执行相应逻辑。
- 延迟注册与严格阶段校验：通过 ArchitectureConfiguration 与 ArchitectureConstants 控制允许的阶段转换与延迟注册策略。

```mermaid
sequenceDiagram
participant Arch as "Architecture"
participant Mod as "AbstractModule"
participant Hook as "IArchitectureLifecycle"
participant Ctx as "IArchitectureContext"
Arch->>Arch : "InstallModule(module)"
Arch->>Hook : "RegisterLifecycleHook(module)"
Arch->>Arch : "Container.RegisterPlurality(module)"
Arch->>Mod : "module.Install(this)"
Arch->>Arch : "NotifyPhaseAwareObjects(phase)"
Arch->>Hook : "OnPhase(phase, this)"
Arch->>Ctx : "Context.GetSystem/Model/Utility..."
```

图表来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L38-L48)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L16-L26)
- [IArchitectureModule.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs#L7-L13)

章节来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L142-L223)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L16-L26)
- [IArchitectureModule.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs#L7-L13)

### 依赖注入与组件注册
- 注册策略：RegisterPlurality 将实例注册到其实现的所有接口与具体类型；RegisterSystem 便捷注册系统实例。
- 解析策略：Get、GetRequired、GetAll、GetAllSorted 提供多样的解析方式；Contains/ContainsInstance/Clear/Frozen 控制与查询。
- 线程安全：使用 ReaderWriterLockSlim 保证并发安全；冻结后禁止进一步注册。

```mermaid
flowchart TD
Start(["开始"]) --> Reg["RegisterPlurality(instance)"]
Reg --> Index["更新类型索引<br/>注册具体类型与接口"]
Index --> Resolve["Get/GetAll/GetRequired"]
Resolve --> Found{"找到实例?"}
Found --> |是| Return["返回实例/列表"]
Found --> |否| NotFound["返回空/抛出异常"]
Index --> Freeze["Freeze() 禁止注册"]
Freeze --> End(["结束"])
Return --> End
NotFound --> End
```

图表来源
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L105-L158)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L211-L294)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L357-L370)

章节来源
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L69-L98)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L105-L158)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L211-L294)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L357-L370)

### 事件系统与模块化通信
- 类型事件：EventBus.Send/Register/UnRegister 提供基于类型的事件发布与订阅。
- 模块化事件：模块在 Install 中注册事件监听，在 OnArchitecturePhase 中根据阶段处理事件，实现模块内聚与跨模块解耦。

```mermaid
sequenceDiagram
participant Comp as "组件(System/Model/Controller)"
participant Bus as "EventBus"
participant Mod as "AbstractModule"
Comp->>Bus : "Send<T>(event)"
Bus-->>Comp : "触发回调"
Mod->>Bus : "Register<T>(handler)"
Bus-->>Mod : "回调触发"
Mod->>Bus : "UnRegister<T>(handler)"
```

图表来源
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs#L16-L54)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L16-L26)

章节来源
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs#L16-L54)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L16-L26)

### 命令与查询的模块化应用
- 命令：AbstractCommand 封装写操作，通过 Context 获取模型与发送事件，实现业务逻辑与 UI 的解耦。
- 查询：AbstractQuery 封装读操作，通过输入参数与返回值实现清晰的职责分离。

```mermaid
flowchart TD
UI["UI/Controller"] --> Cmd["AbstractCommand<TInput>"]
Cmd --> Ctx["Context(架构上下文)"]
Ctx --> Model["Model"]
Model --> Event["EventBus"]
Event --> Sys["System"]
Sys --> Model
UI --> Qry["AbstractQuery<TInput,TResult>"]
Qry --> Model
Model --> UI
```

图表来源
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L11-L27)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L11-L29)

章节来源
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L11-L27)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L11-L29)

### 属性绑定与响应式更新
- BindableProperty 提供 Value 变更通知、注册/注销回调、带初始值的注册等能力，简化 UI 与模型的响应式绑定。

```mermaid
flowchart TD
Prop["BindableProperty<T>"] --> Set["SetValue(Value)"]
Set --> Compare{"值变化?"}
Compare --> |是| Callback["触发回调"]
Compare --> |否| End["结束"]
Callback --> End
```

图表来源
- [BindableProperty.cs](file://GFramework.Core/property/BindableProperty.cs#L24-L41)
- [BindableProperty.cs](file://GFramework.Core/property/BindableProperty.cs#L72-L96)

章节来源
- [BindableProperty.cs](file://GFramework.Core/property/BindableProperty.cs#L24-L41)
- [BindableProperty.cs](file://GFramework.Core/property/BindableProperty.cs#L72-L96)

### 状态机与模块行为编排
- StateMachine 支持状态注册、切换、回退与历史管理，模块可通过状态机编排复杂行为，实现模块内状态驱动的解耦。

```mermaid
flowchart TD
SM["StateMachine"] --> Reg["Register(state)"]
Reg --> Can["CanChangeTo<T>()"]
Can --> |是| To["ChangeTo<T>()"]
Can --> |否| Reject["OnTransitionRejected"]
To --> History["记录历史"]
History --> Enter["OnEnter/OnExit"]
Enter --> Done["完成切换"]
SM --> Back["GoBack()"]
Back --> Pop["弹出历史并切换"]
```

图表来源
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs#L88-L106)
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs#L210-L248)

章节来源
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs#L88-L106)
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs#L210-L248)

### 设置模型与模块化配置
- SettingsModel 提供设置数据节与可应用设置的注册与获取，支持模块化配置与版本兼容。

```mermaid
classDiagram
class SettingsModel {
+GetData<T>()
+RegisterApplicator(applicator)
+GetApplicator<T>()
+TryGet(type, out section)
+All()
}
class ISettingsData
class IApplyAbleSettings
SettingsModel --> ISettingsData : "数据节"
SettingsModel --> IApplyAbleSettings : "应用器"
```

图表来源
- [SettingsModel.cs](file://GFramework.Game/setting/SettingsModel.cs#L19-L94)

章节来源
- [SettingsModel.cs](file://GFramework.Game/setting/SettingsModel.cs#L19-L94)

## 依赖分析
- 组件耦合与内聚：核心组件通过接口与上下文解耦，模块通过 Install 与阶段回调实现内聚功能。
- 直接与间接依赖：模块依赖 Architecture 与 IoC 容器；系统依赖模型与事件；命令/查询依赖上下文。
- 外部依赖与集成：Godot 集成通过节点扩展、信号桥接与日志工厂提供器实现平台特定能力。

```mermaid
graph TB
Arch["Architecture"] --> Ctx["IArchitectureContext"]
Arch --> IOC["IocContainer"]
Arch --> Bus["EventBus"]
Sys["AbstractSystem"] --> Arch
Model["AbstractModel"] --> Arch
Cmd["AbstractCommand"] --> Arch
Qry["AbstractQuery"] --> Arch
Mod["AbstractModule"] --> Arch
Mod --> IOC
Mod --> Bus
Godot["GFramework.Godot"] --> Arch
Game["GFramework.Game"] --> Arch
```

图表来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L72-L77)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs#L13-L62)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs#L11-L34)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L11-L27)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L11-L29)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L9-L33)

章节来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L72-L77)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs#L13-L62)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs#L11-L34)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L11-L27)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L11-L29)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L9-L33)

## 性能考虑
- IoC 容器并发安全：使用 ReaderWriterLockSlim 提升读多写少场景下的并发性能；冻结后禁止注册，避免运行时结构变更带来的开销。
- 事件系统：事件注册与触发采用类型索引与事件实例管理，减少反射与装箱成本。
- 模块化阶段：通过阶段感知与延迟注册策略，避免在 Ready 阶段后进行昂贵的注册操作。
- 状态机历史：限制历史记录大小，平衡回退能力与内存占用。

## 故障排查指南
- 阶段转换异常：当阶段转换不被允许时，架构会记录致命日志并抛出异常。检查 ArchitectureConstants 的允许转换列表与配置项 StrictPhaseValidation。
- 注册时机错误：在 Ready 阶段后尝试注册组件会抛出异常。确认组件注册在 Init 或 BeforeUtilityInit/BeforeModelInit/BeforeSystemInit 阶段。
- IoC 容器冻结：冻结后无法再注册实例，检查是否在 Initialize 后调用注册方法。
- 事件未注销：使用 IUnRegister 或扩展方法在节点退出树时自动注销，避免内存泄漏与逻辑错误。
- 模块安装失败：检查模块 Install 是否正确注册系统与工具，以及 OnArchitecturePhase 的阶段判断逻辑。

章节来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L164-L183)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L218-L223)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L132-L137)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L357-L370)

## 结论
GFramework 的模块化设计通过架构核心、IoC 容器、事件系统与模块接口，实现了高内聚、低耦合的可扩展架构。模块通过 Install 与阶段回调融入架构生命周期，结合命令/查询、属性绑定与状态机，能够有效支撑大型游戏项目的功能划分与协作。在实际项目中，建议遵循接口隔离、依赖倒置与组合优于继承的原则，合理划分模块边界，利用事件与配置模型实现版本兼容与演进。

## 附录
- 快速开始与最佳实践参考：见 GFramework.Core 与 GFramework.Core.Abstractions 的 README。
- 平台集成：Godot 模块提供节点扩展、信号桥接与日志集成，便于在 Godot 中落地模块化架构。
- 游戏层扩展：Game 模块提供设置、存储、序列化与 UI 路由等能力，支持模块化配置与数据持久化。

章节来源
- [README.md](file://GFramework.Core/README.md#L110-L508)
- [README.md](file://GFramework.Core.Abstractions/README.md#L416-L522)
- [README.md](file://GFramework.Godot/README.md#L66-L893)
- [README.md](file://GFramework.Game/README.md#L56-L1402)