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]
16 KiB
16 KiB
项目概述
**本文档引用的文件** - [README.md](file://README.md) - [GFramework.Core/README.md](file://GFramework.Core/README.md) - [GFramework.Core.Abstractions/README.md](file://GFramework.Core.Abstractions/README.md) - [GFramework.Core/architecture/README.md](file://GFramework.Core/architecture/README.md) - [GFramework.Core/events/README.md](file://GFramework.Core/events/README.md) - [GFramework.Core/ioc/README.md](file://GFramework.Core/ioc/README.md) - [GFramework.Core/command/README.md](file://GFramework.Core/command/README.md) - [GFramework.Core/query/README.md](file://GFramework.Core/query/README.md) - [GFramework.Core/property/README.md](file://GFramework.Core/property/README.md) - [GFramework.Core/logging/README.md](file://GFramework.Core/logging/README.md) - [GFramework.Core/system/README.md](file://GFramework.Core/system/README.md) - [GFramework.Core/model/README.md](file://GFramework.Core/model/README.md) - [GFramework.Core/utility/README.md](file://GFramework.Core/utility/README.md) - [GFramework.Game/README.md](file://GFramework.Game/README.md) - [GFramework.Godot/README.md](file://GFramework.Godot/README.md)目录
引言
GFramework 是一个面向游戏开发场景的综合性 C# 架构框架，强调模块化、平台无关与 Clean Architecture 设计。它通过命令查询职责分离（CQRS）、事件驱动、依赖注入、属性绑定、日志框架与生命周期管理等核心能力，帮助团队构建清晰、可维护、可扩展的游戏应用。
- 平台无关：核心模块 GFramework.Core 与 Godot 解耦，可在任意 .NET 环境运行。
- 深度集成：通过 GFramework.Godot 提供与 Godot 引擎的无缝集成与扩展。
- 清洁架构：从 View/UI 到 Utility 的分层设计，职责清晰、易于测试与演进。
项目结构
项目采用多模块分层组织，核心模块与平台集成模块分离，便于移植与扩展：
graph TB
subgraph "核心模块"
Core["GFramework.Core"]
CoreAbst["GFramework.Core.Abstractions"]
Game["GFramework.Game"]
GameAbst["GFramework.Game.Abstractions"]
end
subgraph "平台集成"
Godot["GFramework.Godot"]
GodotSrcGen["GFramework.Godot.SourceGenerators"]
SrcGen["GFramework.SourceGenerators"]
SrcGenAbst["GFramework.SourceGenerators.Abstractions"]
end
Core --> CoreAbst
Game --> Core
Game --> GameAbst
Godot --> Core
Godot --> CoreAbst
GodotSrcGen --> Godot
SrcGen --> Core
SrcGenAbst --> Core
图表来源
章节来源
核心组件
GFramework 的核心能力围绕以下组件展开，它们共同构成 Clean Architecture 的分层与横切关注点：
- 架构与生命周期：IArchitecture、IArchitectureContext、IArchitectureModule、ArchitecturePhase
- 依赖注入：IIocContainer、IocContainer
- 命令查询分离：ICommand/ICommand、IQuery、CommandBus、QueryBus
- 事件系统：IEventBus、EasyEvent/EasyEventGeneric、EventBus、UnRegisterList
- 属性绑定：IBindableProperty/IReadonlyBindableProperty、BindableProperty
- 日志框架：ILogger、ILoggerFactory、ILoggerFactoryProvider、LogLevel
- 数据模型：IModel、AbstractModel
- 业务系统：ISystem、AbstractSystem
- 工具层：IUtility、IContextUtility、AbstractContextUtility
- 游戏特定：资产目录、存储系统、序列化、UI 路由与过渡管线等
章节来源
- GFramework.Core.Abstractions/README.md
- GFramework.Core/architecture/README.md
- GFramework.Core/ioc/README.md
- GFramework.Core/command/README.md
- GFramework.Core/query/README.md
- GFramework.Core/events/README.md
- GFramework.Core/property/README.md
- GFramework.Core/logging/README.md
- GFramework.Core/model/README.md
- GFramework.Core/system/README.md
- GFramework.Core/utility/README.md
架构总览
GFramework 采用 Clean Architecture 的五层结构，并引入横切关注点（命令/查询/事件）贯穿各层，形成“View/UI → Controller → System → Model → Utility”的数据与控制流。
graph TB
View["View/UI<br/>用户界面"] --> Controller["Controller<br/>处理用户输入"]
Controller --> System["System<br/>业务逻辑"]
System --> Model["Model<br/>游戏状态"]
Model --> Utility["Utility<br/>无状态工具"]
Controller -. 横切 .-> Cmd["Command/Query/Event"]
System -. 横切 .-> Cmd
Model -. 横切 .-> Cmd
Utility -. 横切 .-> Cmd
图表来源
章节来源
详细组件分析
依赖注入（IoC）
- IocContainer 提供注册、解析与生命周期管理，支持单例、多实现、排序解析与冻结保护。
- Architecture 内置 IoC 容器，统一管理 System、Model、Utility 的注册与获取。
- 最佳实践：在 Init 中集中注册；使用接口注册与解析；避免运行时频繁注册；初始化后冻结容器。
classDiagram
class IIocContainer {
+Register(instance)
+RegisterSingleton(instance)
+RegisterPlurality(instance)
+RegisterSystem(system)
+Get~T~()
+GetAll~T~()
+GetRequired~T~()
+GetAllSorted~T~(comparison)
+Contains~T~()
+ContainsInstance(instance)
+Clear()
+Freeze()
}
class IocContainer {
-typeIndex : Dictionary
-objects : HashSet
-lock : ReaderWriterLockSlim
-frozen : bool
}
IIocContainer <|.. IocContainer
图表来源
章节来源
事件系统（Event System）
- IEventBus 提供类型化事件的注册与发送；EasyEvent/EasyEventGeneric 支持无参/单参/双参事件。
- UnRegisterList 统一管理注销，配合 Godot 节点生命周期自动清理。
- 架构事件：ArchitectureLifecycleReadyEvent、ArchitectureDestroyingEvent、ArchitectureDestroyedEvent、ArchitectureFailedInitializationEvent。
sequenceDiagram
participant Sys as "System"
participant Bus as "EventBus"
participant Ctrl as "Controller/UI"
Sys->>Bus : Register<T>(handler)
Sys->>Bus : Send<T>(event)
Bus-->>Ctrl : 触发回调
Ctrl->>Ctrl : UnRegisterWhenNodeExitTree(node)
图表来源
章节来源
命令查询分离（CQRS）
- ICommand/ICommand 封装写操作；IQuery 封装读操作。
- CommandBus/QueryBus 统一分发与执行；EmptyCommandInput/EmptyQueryInput 简化无参场景。
- 使用建议：命令原子性、无状态、参数结构化；查询只读、可组合、避免过度查询。
flowchart TD
Start(["发起操作"]) --> CheckType{"命令还是查询?"}
CheckType --> |命令| SendCmd["CommandBus.Send(command)"]
CheckType --> |查询| SendQry["QueryBus.Send(query)"]
SendCmd --> ExecCmd["执行 OnExecute<br/>修改 Model/发送事件"]
SendQry --> ExecQry["执行 Do()<br/>返回结果"]
ExecCmd --> End(["完成"])
ExecQry --> End
图表来源
章节来源
属性绑定（Property Binding）
- IBindableProperty/IReadonlyBindableProperty 支持值变化监听与响应式更新。
- RegisterWithInitValue 立即触发回调，适合 UI 绑定；SetValueWithoutEvent 批量更新避免频繁触发。
- 与事件系统协同，实现 Model → UI 的自动更新。
sequenceDiagram
participant Model as "Model"
participant Prop as "BindableProperty<T>"
participant UI as "UI/Controller"
Model->>Prop : Value = newValue
Prop-->>UI : 触发回调(监听者)
UI->>UI : 更新界面显示
图表来源
章节来源
日志框架（Logging）
- ILogger/ILoggerFactory/ILoggerFactoryProvider 提供多级别日志记录与工厂解析。
- 默认 Info 级别，支持 Trace/Debug/Info/Warning/Error/Fatal。
- 建议：为模块创建独立 Logger；异常日志记录；分类使用日志；合理设置最小级别。
章节来源
数据模型（Model）
- IModel/AbstractModel 管理数据与状态；监听属性变化并发送事件。
- 最佳实践：Model 仅存储数据；复杂逻辑放入 System；避免 Model 间直接调用。
章节来源
业务系统（System）
- ISystem/AbstractSystem 处理业务逻辑，响应事件并协调 Model。
- 最佳实践：单一职责、事件驱动、无状态或少状态、初始化注册。
章节来源
工具层（Utility）
- IUtility/IContextUtility 提供无状态工具方法；AbstractContextUtility 支持日志与上下文。
- 最佳实践：纯函数、单一职责、避免依赖架构组件。
章节来源
游戏特定功能（GFramework.Game）
- 模块化架构：AbstractModule 支持生命周期阶段感知与模块安装。
- 资产管理：统一资源目录、类型安全、映射与缓存。
- 存储系统：分层存储、多格式支持、异步操作、版本兼容。
- 序列化系统：JSON 集成、自定义转换器、版本化序列化与迁移。
章节来源
平台集成（GFramework.Godot）
- 架构生命周期绑定：自动与 Godot 场景树同步，节点销毁时自动清理。
- Node 扩展方法：50+ 实用扩展，简化节点查找、验证、场景树操作、输入处理与异步等待。
- 信号系统：SignalBuilder 流畅 API，桥接 Godot 信号与框架事件。
- 节点池化：AbstractNodePoolSystem 支持高频节点创建/销毁的内存友好策略。
- 资源管理：ResourceLoadUtility、自定义资源工厂。
- 日志系统：GodotLogger/GodotLoggerFactory，与引擎日志集成。
章节来源
依赖分析
- 核心依赖：GFramework.Core 与 GFramework.Core.Abstractions 提供抽象契约与实现。
- 平台集成：GFramework.Godot 依赖 Core 与 Abstractions，并提供 Godot 特定扩展。
- 游戏模块：GFramework.Game 依赖 Core 与 Game.Abstractions，提供资产、存储、序列化等游戏功能。
- 源码生成器：GFramework.SourceGenerators 与 GFramework.Godot.SourceGenerators 提供上下文感知、日志与枚举扩展的零运行时开销代码生成。
graph LR
Core["GFramework.Core"] --> Abst["GFramework.Core.Abstractions"]
Game["GFramework.Game"] --> Core
Game --> GameAbst["GFramework.Game.Abstractions"]
Godot["GFramework.Godot"] --> Core
Godot --> Abst
SrcGen["GFramework.SourceGenerators"] --> Core
GodotSrcGen["GFramework.Godot.SourceGenerators"] --> Godot
图表来源
章节来源
性能考量
- 事件系统：避免每帧触发高频事件；使用结构体事件减少 GC；条件事件过滤。
- 属性绑定：使用 SetValueWithoutEvent 批量更新；自定义比较器避免浮点误差导致的频繁触发。
- IoC 容器：初始化后冻结容器；避免运行时频繁注册；合理使用 GetRequired/Contains。
- 游戏模块：分层存储命名与缓存；批量写入与异步 I/O；序列化格式与压缩策略；对象池化降低 GC 压力。
故障排除指南
- 事件未注销：使用 UnRegisterList 或 UnRegisterWhenNodeExitTree；在 _ExitTree 中统一注销。
- 循环依赖：避免在事件处理器中直接发送新事件；通过命令打破循环。
- 初始化失败：检查 ArchitecturePhase 与 FailedInitialization 事件；逐步排查注册顺序与依赖。
- 日志级别：确认 LoggerFactoryResolver.Provider 与 MinLevel 设置；区分 Info/Debug/Warn/Error/Fatal。
- 模块安装：确保在 ArchitecturePhase.Ready 前注册生命周期钩子；模块安装顺序影响依赖解析。
章节来源
- GFramework.Core/events/README.md
- GFramework.Core/logging/README.md
- GFramework.Core/architecture/README.md
结论
GFramework 以 Clean Architecture 为核心，结合 CQRS、事件驱动、依赖注入、属性绑定与生命周期管理，为游戏开发提供了平台无关、模块化、可扩展的基础设施。通过 GFramework.Game 与 GFramework.Godot，开发者可以在不同平台上快速落地架构理念，并获得强大的游戏功能与平台集成能力。
附录
技术栈概览
- .NET：6.0+
- Godot：4.5+
- 依赖库：Newtonsoft.Json 等（详见各模块 README）
章节来源
快速开始与安装
- 安装 NuGet 包：GeWuYou.GFramework.Core、GeWuYou.GFramework.Core.Abstractions、GeWuYou.GFramework.Game、GeWuYou.GFramework.Game.Abstractions、GeWuYou.GFramework.SourceGenerators、GeWuYou.GFramework.Godot（Godot 项目）。
- 基本使用：定义架构（继承 Architecture）、注册 Model/System/Utility、在 Controller 中使用依赖注入、通过 SendCommand/SendQuery/事件通信。
章节来源