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]
19 KiB
19 KiB
模块化设计
**本文引用的文件** - [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)目录
简介
本教程围绕 GFramework 的模块化设计展开，系统讲解模块化架构的设计原则与实现策略，包括关注点分离、依赖注入、接口抽象、事件驱动与生命周期管理等核心概念。教程将结合 GFramework.Core、GFramework.Core.Abstractions、GFramework.Game、GFramework.Godot 等模块，给出可复用的模块组件设计思路、模块间解耦策略、模块生命周期管理方法，并说明在大型游戏项目中的应用实践，涵盖功能模块划分、协作模式与版本兼容性管理。最后提供最佳实践与常见问题的解决方案。
项目结构
GFramework 采用分层与模块化相结合的组织方式：
- GFramework.Core：平台无关的核心框架，提供架构、IoC、事件、命令/查询、属性绑定、状态机等通用能力。
- GFramework.Core.Abstractions：核心抽象契约，定义接口、枚举与配置，确保可移植性与可替换性。
- GFramework.Game：游戏特定功能模块，提供设置、存储、序列化、UI 路由等游戏开发常用能力，并内置模块化架构。
- GFramework.Godot：Godot 平台集成模块，提供节点扩展、信号桥接、节点池化、日志集成等能力，与核心框架深度结合。
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
图表来源
章节来源
核心组件
- 架构与生命周期：通过 Architecture 管理组件注册、初始化阶段与销毁流程，支持模块安装与阶段感知。
- IoC 容器：IocContainer 提供注册、解析、冻结与多实例管理，支撑依赖注入与组件解耦。
- 事件系统：EventBus 提供类型事件的发送、注册与注销，实现跨层松耦合通信。
- 模块化架构：AbstractModule 与 IArchitectureModule 定义模块安装与阶段回调，支持模块化功能拆分与生命周期管理。
- 命令/查询：AbstractCommand/AbstractQuery 封装写/读操作，配合总线实现职责分离。
- 属性绑定：BindableProperty 支持数据变化通知，简化 UI 与模型的响应式绑定。
- 状态机：StateMachine 管理状态注册、切换与历史，支持状态驱动的模块行为。
- 设置模型：SettingsModel 管理设置数据与可应用设置，支持模块化配置与版本兼容。
章节来源
- Architecture.cs
- IocContainer.cs
- EventBus.cs
- AbstractModule.cs
- IArchitectureModule.cs
- AbstractCommand.cs
- AbstractQuery.cs
- BindableProperty.cs
- StateMachine.cs
- SettingsModel.cs
架构总览
GFramework 的模块化架构以 Architecture 为核心，通过 IoC 容器管理组件生命周期，借助事件系统实现跨层通信，模块通过 IArchitectureModule 接口安装到架构并在不同阶段执行逻辑。游戏层与平台层在此基础上扩展出设置、存储、序列化、UI 路由与 Godot 集成等能力。
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
- IocContainer.cs
- EventBus.cs
- AbstractModule.cs
- IArchitectureModule.cs
- AbstractCommand.cs
- AbstractQuery.cs
- BindableProperty.cs
- StateMachine.cs
- SettingsModel.cs
详细组件分析
模块化架构与生命周期
- 模块安装：通过 Architecture.InstallModule 注册模块、注册生命周期钩子、调用模块 Install 并记录日志。
- 阶段感知：模块实现 IArchitecturePhaseAware，在架构不同阶段（如 BeforeUtilityInit、AfterModelInit、Ready、Destroying 等）执行相应逻辑。
- 延迟注册与严格阶段校验：通过 ArchitectureConfiguration 与 ArchitectureConstants 控制允许的阶段转换与延迟注册策略。
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..."
图表来源
章节来源
依赖注入与组件注册
- 注册策略：RegisterPlurality 将实例注册到其实现的所有接口与具体类型；RegisterSystem 便捷注册系统实例。
- 解析策略：Get、GetRequired、GetAll、GetAllSorted 提供多样的解析方式；Contains/ContainsInstance/Clear/Frozen 控制与查询。
- 线程安全：使用 ReaderWriterLockSlim 保证并发安全；冻结后禁止进一步注册。
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
图表来源
章节来源
事件系统与模块化通信
- 类型事件：EventBus.Send/Register/UnRegister 提供基于类型的事件发布与订阅。
- 模块化事件：模块在 Install 中注册事件监听，在 OnArchitecturePhase 中根据阶段处理事件，实现模块内聚与跨模块解耦。
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)"
图表来源
章节来源
命令与查询的模块化应用
- 命令：AbstractCommand 封装写操作，通过 Context 获取模型与发送事件，实现业务逻辑与 UI 的解耦。
- 查询：AbstractQuery 封装读操作，通过输入参数与返回值实现清晰的职责分离。
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
图表来源
章节来源
属性绑定与响应式更新
- BindableProperty 提供 Value 变更通知、注册/注销回调、带初始值的注册等能力，简化 UI 与模型的响应式绑定。
flowchart TD
Prop["BindableProperty<T>"] --> Set["SetValue(Value)"]
Set --> Compare{"值变化?"}
Compare --> |是| Callback["触发回调"]
Compare --> |否| End["结束"]
Callback --> End
图表来源
章节来源
状态机与模块行为编排
- StateMachine 支持状态注册、切换、回退与历史管理，模块可通过状态机编排复杂行为，实现模块内状态驱动的解耦。
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["弹出历史并切换"]
图表来源
章节来源
设置模型与模块化配置
- SettingsModel 提供设置数据节与可应用设置的注册与获取，支持模块化配置与版本兼容。
classDiagram
class SettingsModel {
+GetData<T>()
+RegisterApplicator(applicator)
+GetApplicator<T>()
+TryGet(type, out section)
+All()
}
class ISettingsData
class IApplyAbleSettings
SettingsModel --> ISettingsData : "数据节"
SettingsModel --> IApplyAbleSettings : "应用器"
图表来源
章节来源
依赖分析
- 组件耦合与内聚：核心组件通过接口与上下文解耦，模块通过 Install 与阶段回调实现内聚功能。
- 直接与间接依赖：模块依赖 Architecture 与 IoC 容器；系统依赖模型与事件；命令/查询依赖上下文。
- 外部依赖与集成：Godot 集成通过节点扩展、信号桥接与日志工厂提供器实现平台特定能力。
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
- AbstractSystem.cs
- AbstractModel.cs
- AbstractCommand.cs
- AbstractQuery.cs
- AbstractModule.cs
章节来源
- Architecture.cs
- AbstractSystem.cs
- AbstractModel.cs
- AbstractCommand.cs
- AbstractQuery.cs
- AbstractModule.cs
性能考虑
- IoC 容器并发安全：使用 ReaderWriterLockSlim 提升读多写少场景下的并发性能；冻结后禁止注册，避免运行时结构变更带来的开销。
- 事件系统：事件注册与触发采用类型索引与事件实例管理，减少反射与装箱成本。
- 模块化阶段：通过阶段感知与延迟注册策略，避免在 Ready 阶段后进行昂贵的注册操作。
- 状态机历史：限制历史记录大小，平衡回退能力与内存占用。
故障排查指南
- 阶段转换异常：当阶段转换不被允许时，架构会记录致命日志并抛出异常。检查 ArchitectureConstants 的允许转换列表与配置项 StrictPhaseValidation。
- 注册时机错误：在 Ready 阶段后尝试注册组件会抛出异常。确认组件注册在 Init 或 BeforeUtilityInit/BeforeModelInit/BeforeSystemInit 阶段。
- IoC 容器冻结：冻结后无法再注册实例，检查是否在 Initialize 后调用注册方法。
- 事件未注销：使用 IUnRegister 或扩展方法在节点退出树时自动注销，避免内存泄漏与逻辑错误。
- 模块安装失败：检查模块 Install 是否正确注册系统与工具，以及 OnArchitecturePhase 的阶段判断逻辑。
章节来源
结论
GFramework 的模块化设计通过架构核心、IoC 容器、事件系统与模块接口，实现了高内聚、低耦合的可扩展架构。模块通过 Install 与阶段回调融入架构生命周期，结合命令/查询、属性绑定与状态机，能够有效支撑大型游戏项目的功能划分与协作。在实际项目中，建议遵循接口隔离、依赖倒置与组合优于继承的原则，合理划分模块边界，利用事件与配置模型实现版本兼容与演进。
附录
- 快速开始与最佳实践参考：见 GFramework.Core 与 GFramework.Core.Abstractions 的 README。
- 平台集成：Godot 模块提供节点扩展、信号桥接与日志集成，便于在 Godot 中落地模块化架构。
- 游戏层扩展：Game 模块提供设置、存储、序列化与 UI 路由等能力，支持模块化配置与数据持久化。
章节来源