mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-26 06:16:43 +08:00
a79f02c987
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件 - 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明 - 提供完整的 API 使用示例路径、最佳实践与性能建议 - 包含架构图、依赖关系图与故障排查指南 - 添加测试用例参考与扩展方法说明 - [skip ci]
348 lines
16 KiB
Markdown
348 lines
16 KiB
Markdown
# 项目概述
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [引言](#引言)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 引言
|
||
GFramework 是一个面向游戏开发场景的综合性 C# 架构框架，强调模块化、平台无关与 Clean Architecture 设计。它通过命令查询职责分离（CQRS）、事件驱动、依赖注入、属性绑定、日志框架与生命周期管理等核心能力，帮助团队构建清晰、可维护、可扩展的游戏应用。
|
||
|
||
- 平台无关：核心模块 GFramework.Core 与 Godot 解耦，可在任意 .NET 环境运行。
|
||
- 深度集成：通过 GFramework.Godot 提供与 Godot 引擎的无缝集成与扩展。
|
||
- 清洁架构：从 View/UI 到 Utility 的分层设计，职责清晰、易于测试与演进。
|
||
|
||
## 项目结构
|
||
项目采用多模块分层组织，核心模块与平台集成模块分离，便于移植与扩展：
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [README.md](file://README.md#L33-L51)
|
||
- [GFramework.Core/README.md](file://GFramework.Core/README.md#L1-L508)
|
||
- [GFramework.Game/README.md](file://GFramework.Game/README.md#L1-L1402)
|
||
- [GFramework.Godot/README.md](file://GFramework.Godot/README.md#L1-L893)
|
||
|
||
章节来源
|
||
- [README.md](file://README.md#L33-L51)
|
||
- [GFramework.Core/README.md](file://GFramework.Core/README.md#L1-L508)
|
||
|
||
## 核心组件
|
||
GFramework 的核心能力围绕以下组件展开，它们共同构成 Clean Architecture 的分层与横切关注点：
|
||
|
||
- 架构与生命周期：IArchitecture、IArchitectureContext、IArchitectureModule、ArchitecturePhase
|
||
- 依赖注入：IIocContainer、IocContainer
|
||
- 命令查询分离：ICommand/ICommand<TResult>、IQuery<TResult>、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](file://GFramework.Core.Abstractions/README.md#L1-L522)
|
||
- [GFramework.Core/architecture/README.md](file://GFramework.Core/architecture/README.md#L1-L503)
|
||
- [GFramework.Core/ioc/README.md](file://GFramework.Core/ioc/README.md#L1-L681)
|
||
- [GFramework.Core/command/README.md](file://GFramework.Core/command/README.md#L1-L309)
|
||
- [GFramework.Core/query/README.md](file://GFramework.Core/query/README.md#L1-L433)
|
||
- [GFramework.Core/events/README.md](file://GFramework.Core/events/README.md#L1-L523)
|
||
- [GFramework.Core/property/README.md](file://GFramework.Core/property/README.md#L1-L342)
|
||
- [GFramework.Core/logging/README.md](file://GFramework.Core/logging/README.md#L1-L364)
|
||
- [GFramework.Core/model/README.md](file://GFramework.Core/model/README.md#L1-L184)
|
||
- [GFramework.Core/system/README.md](file://GFramework.Core/system/README.md#L1-L544)
|
||
- [GFramework.Core/utility/README.md](file://GFramework.Core/utility/README.md#L1-L613)
|
||
|
||
## 架构总览
|
||
GFramework 采用 Clean Architecture 的五层结构，并引入横切关注点（命令/查询/事件）贯穿各层，形成“View/UI → Controller → System → Model → Utility”的数据与控制流。
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [GFramework.Core/README.md](file://GFramework.Core/README.md#L42-L108)
|
||
- [GFramework.Core/architecture/README.md](file://GFramework.Core/architecture/README.md#L107-L124)
|
||
|
||
章节来源
|
||
- [GFramework.Core/README.md](file://GFramework.Core/README.md#L42-L108)
|
||
|
||
## 详细组件分析
|
||
|
||
### 依赖注入（IoC）
|
||
- IocContainer 提供注册、解析与生命周期管理，支持单例、多实现、排序解析与冻结保护。
|
||
- Architecture 内置 IoC 容器，统一管理 System、Model、Utility 的注册与获取。
|
||
- 最佳实践：在 Init 中集中注册；使用接口注册与解析；避免运行时频繁注册；初始化后冻结容器。
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [GFramework.Core/ioc/README.md](file://GFramework.Core/ioc/README.md#L10-L681)
|
||
|
||
章节来源
|
||
- [GFramework.Core/ioc/README.md](file://GFramework.Core/ioc/README.md#L1-L681)
|
||
- [GFramework.Core/architecture/README.md](file://GFramework.Core/architecture/README.md#L148-L173)
|
||
|
||
### 事件系统（Event System）
|
||
- IEventBus 提供类型化事件的注册与发送；EasyEvent/EasyEventGeneric 支持无参/单参/双参事件。
|
||
- UnRegisterList 统一管理注销，配合 Godot 节点生命周期自动清理。
|
||
- 架构事件：ArchitectureLifecycleReadyEvent、ArchitectureDestroyingEvent、ArchitectureDestroyedEvent、ArchitectureFailedInitializationEvent。
|
||
|
||
```mermaid
|
||
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)
|
||
```
|
||
|
||
图表来源
|
||
- [GFramework.Core/events/README.md](file://GFramework.Core/events/README.md#L138-L162)
|
||
- [GFramework.Core/events/README.md](file://GFramework.Core/events/README.md#L213-L223)
|
||
|
||
章节来源
|
||
- [GFramework.Core/events/README.md](file://GFramework.Core/events/README.md#L1-L523)
|
||
|
||
### 命令查询分离（CQRS）
|
||
- ICommand/ICommand<TResult> 封装写操作；IQuery<TResult> 封装读操作。
|
||
- CommandBus/QueryBus 统一分发与执行；EmptyCommandInput/EmptyQueryInput 简化无参场景。
|
||
- 使用建议：命令原子性、无状态、参数结构化；查询只读、可组合、避免过度查询。
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [GFramework.Core/command/README.md](file://GFramework.Core/command/README.md#L150-L173)
|
||
- [GFramework.Core/query/README.md](file://GFramework.Core/query/README.md#L50-L65)
|
||
|
||
章节来源
|
||
- [GFramework.Core/command/README.md](file://GFramework.Core/command/README.md#L1-L309)
|
||
- [GFramework.Core/query/README.md](file://GFramework.Core/query/README.md#L1-L433)
|
||
|
||
### 属性绑定（Property Binding）
|
||
- IBindableProperty/IReadonlyBindableProperty 支持值变化监听与响应式更新。
|
||
- RegisterWithInitValue 立即触发回调，适合 UI 绑定；SetValueWithoutEvent 批量更新避免频繁触发。
|
||
- 与事件系统协同，实现 Model → UI 的自动更新。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Model as "Model"
|
||
participant Prop as "BindableProperty<T>"
|
||
participant UI as "UI/Controller"
|
||
Model->>Prop : Value = newValue
|
||
Prop-->>UI : 触发回调(监听者)
|
||
UI->>UI : 更新界面显示
|
||
```
|
||
|
||
图表来源
|
||
- [GFramework.Core/property/README.md](file://GFramework.Core/property/README.md#L45-L100)
|
||
|
||
章节来源
|
||
- [GFramework.Core/property/README.md](file://GFramework.Core/property/README.md#L1-L342)
|
||
|
||
### 日志框架（Logging）
|
||
- ILogger/ILoggerFactory/ILoggerFactoryProvider 提供多级别日志记录与工厂解析。
|
||
- 默认 Info 级别，支持 Trace/Debug/Info/Warning/Error/Fatal。
|
||
- 建议：为模块创建独立 Logger；异常日志记录；分类使用日志；合理设置最小级别。
|
||
|
||
章节来源
|
||
- [GFramework.Core/logging/README.md](file://GFramework.Core/logging/README.md#L1-L364)
|
||
|
||
### 数据模型（Model）
|
||
- IModel/AbstractModel 管理数据与状态；监听属性变化并发送事件。
|
||
- 最佳实践：Model 仅存储数据；复杂逻辑放入 System；避免 Model 间直接调用。
|
||
|
||
章节来源
|
||
- [GFramework.Core/model/README.md](file://GFramework.Core/model/README.md#L1-L184)
|
||
|
||
### 业务系统（System）
|
||
- ISystem/AbstractSystem 处理业务逻辑，响应事件并协调 Model。
|
||
- 最佳实践：单一职责、事件驱动、无状态或少状态、初始化注册。
|
||
|
||
章节来源
|
||
- [GFramework.Core/system/README.md](file://GFramework.Core/system/README.md#L1-L544)
|
||
|
||
### 工具层（Utility）
|
||
- IUtility/IContextUtility 提供无状态工具方法；AbstractContextUtility 支持日志与上下文。
|
||
- 最佳实践：纯函数、单一职责、避免依赖架构组件。
|
||
|
||
章节来源
|
||
- [GFramework.Core/utility/README.md](file://GFramework.Core/utility/README.md#L1-L613)
|
||
|
||
### 游戏特定功能（GFramework.Game）
|
||
- 模块化架构：AbstractModule 支持生命周期阶段感知与模块安装。
|
||
- 资产管理：统一资源目录、类型安全、映射与缓存。
|
||
- 存储系统：分层存储、多格式支持、异步操作、版本兼容。
|
||
- 序列化系统：JSON 集成、自定义转换器、版本化序列化与迁移。
|
||
|
||
章节来源
|
||
- [GFramework.Game/README.md](file://GFramework.Game/README.md#L1-L1402)
|
||
|
||
### 平台集成（GFramework.Godot）
|
||
- 架构生命周期绑定：自动与 Godot 场景树同步，节点销毁时自动清理。
|
||
- Node 扩展方法：50+ 实用扩展，简化节点查找、验证、场景树操作、输入处理与异步等待。
|
||
- 信号系统：SignalBuilder 流畅 API，桥接 Godot 信号与框架事件。
|
||
- 节点池化：AbstractNodePoolSystem 支持高频节点创建/销毁的内存友好策略。
|
||
- 资源管理：ResourceLoadUtility、自定义资源工厂。
|
||
- 日志系统：GodotLogger/GodotLoggerFactory，与引擎日志集成。
|
||
|
||
章节来源
|
||
- [GFramework.Godot/README.md](file://GFramework.Godot/README.md#L1-L893)
|
||
|
||
## 依赖分析
|
||
- 核心依赖：GFramework.Core 与 GFramework.Core.Abstractions 提供抽象契约与实现。
|
||
- 平台集成：GFramework.Godot 依赖 Core 与 Abstractions，并提供 Godot 特定扩展。
|
||
- 游戏模块：GFramework.Game 依赖 Core 与 Game.Abstractions，提供资产、存储、序列化等游戏功能。
|
||
- 源码生成器：GFramework.SourceGenerators 与 GFramework.Godot.SourceGenerators 提供上下文感知、日志与枚举扩展的零运行时开销代码生成。
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [README.md](file://README.md#L33-L51)
|
||
- [GFramework.Game/README.md](file://GFramework.Game/README.md#L1379-L1387)
|
||
|
||
章节来源
|
||
- [README.md](file://README.md#L33-L51)
|
||
- [GFramework.Game/README.md](file://GFramework.Game/README.md#L1379-L1387)
|
||
|
||
## 性能考量
|
||
- 事件系统：避免每帧触发高频事件；使用结构体事件减少 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](file://GFramework.Core/events/README.md#L437-L463)
|
||
- [GFramework.Core/logging/README.md](file://GFramework.Core/logging/README.md#L215-L252)
|
||
- [GFramework.Core/architecture/README.md](file://GFramework.Core/architecture/README.md#L283-L325)
|
||
|
||
## 结论
|
||
GFramework 以 Clean Architecture 为核心，结合 CQRS、事件驱动、依赖注入、属性绑定与生命周期管理，为游戏开发提供了平台无关、模块化、可扩展的基础设施。通过 GFramework.Game 与 GFramework.Godot，开发者可以在不同平台上快速落地架构理念，并获得强大的游戏功能与平台集成能力。
|
||
|
||
## 附录
|
||
|
||
### 技术栈概览
|
||
- .NET：6.0+
|
||
- Godot：4.5+
|
||
- 依赖库：Newtonsoft.Json 等（详见各模块 README）
|
||
|
||
章节来源
|
||
- [README.md](file://README.md#L6-L7)
|
||
- [GFramework.Game/README.md](file://GFramework.Game/README.md#L1389-L1393)
|
||
|
||
### 快速开始与安装
|
||
- 安装 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/事件通信。
|
||
|
||
章节来源
|
||
- [README.md](file://README.md#L88-L105)
|
||
- [README.md](file://README.md#L107-L159)
|
||
- [README.md](file://README.md#L161-L233)
|
||
- [README.md](file://README.md#L255-L274) |