GFramework/.qoder/repowiki/zh/content/教程和指南/从零开始教程.md

从零开始教程

**本文档引用的文件** - [README.md](file://README.md) - [GFramework.Core/README.md](file://GFramework.Core/README.md) - [GFramework.Core/GFramework.Core.csproj](file://GFramework.Core/GFramework.Core.csproj) - [GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj](file://GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj) - [GFramework.Game/README.md](file://GFramework.Game/README.md) - [GFramework.Godot/README.md](file://GFramework.Godot/README.md) - [GFramework.Core/architecture/Architecture.cs](file://GFramework.Core/architecture/Architecture.cs) - [GFramework.Core/model/AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs) - [GFramework.Core/system/AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs) - [GFramework.Core/command/AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs) - [GFramework.Core/query/AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs) - [GFramework.Core/property/BindableProperty.cs](file://GFramework.Core/property/BindableProperty.cs) - [GFramework.Core.Tests/system/TestSystem.cs](file://GFramework.Core.Tests/system/TestSystem.cs) - [GFramework.Core.Tests/model/TestModel.cs](file://GFramework.Core.Tests/model/TestModel.cs)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构概览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排除指南
9. 结论
10. 附录

简介

本教程面向希望使用GFramework从零开始创建游戏项目的开发者。GFramework是一个基于CQRS、MVC和事件驱动的轻量级游戏开发架构框架，提供与平台无关的核心模块以及针对Godot引擎的深度集成。本教程将涵盖环境准备、项目创建、架构设计、功能实现、测试验证和项目打包的完整流程。

项目结构

GFramework采用模块化设计，主要包含以下核心模块：

graph TB
subgraph "核心框架"
Core[GFramework.Core<br/>平台无关核心]
CoreAbstraction[GFramework.Core.Abstractions<br/>核心接口定义]
end
subgraph "游戏功能"
Game[GFramework.Game<br/>游戏特定功能]
GameAbstraction[GFramework.Game.Abstractions<br/>游戏接口定义]
end
subgraph "平台集成"
Godot[GFramework.Godot<br/>Godot引擎集成]
SourceGen[GFramework.SourceGenerators<br/>通用源码生成器]
GodotSourceGen[GFramework.Godot.SourceGenerators<br/>Godot源码生成器]
end
subgraph "测试"
CoreTests[GFramework.Core.Tests<br/>核心单元测试]
end
Core --> CoreAbstraction
Game --> GameAbstraction
Godot --> Core
SourceGen --> Core
GodotSourceGen --> Godot
CoreTests --> Core

图表来源

• GFramework.Core/GFramework.Core.csproj
• GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj

章节来源

• README.md
• GFramework.Core/README.md

核心组件

GFramework的核心架构遵循清洁架构原则，包含五个主要层次：

五层架构设计

graph TB
subgraph "UI层"
UI[用户界面]
end
subgraph "控制层"
Controller[控制器]
end
subgraph "逻辑层"
System[系统]
end
subgraph "数据层"
Model[模型]
end
subgraph "工具层"
Utility[工具]
end
subgraph "横切关注点"
Command[命令]
Query[查询]
Event[事件]
end
UI --> Controller
Controller --> Command
Controller --> Query
Command --> System
Query --> Model
System --> Model
Model --> Event
Event --> Controller
Event --> System
Event --> Model
Utility -.-> Controller
Utility -.-> System
Utility -.-> Model

图表来源

• GFramework.Core/README.md

架构阶段管理

GFramework采用阶段化的生命周期管理模式：

stateDiagram-v2
[*] --> 初始化
初始化 --> BeforeUtilityInit
BeforeUtilityInit --> AfterUtilityInit
AfterUtilityInit --> BeforeModelInit
BeforeModelInit --> AfterModelInit
AfterModelInit --> BeforeSystemInit
BeforeSystemInit --> AfterSystemInit
AfterSystemInit --> 就绪
就绪 --> 销毁中
销毁中 --> 已销毁
已销毁 --> [*]
note right of 初始化
架构创建和基础环境初始化
end note
note right of 就绪
所有组件初始化完成
end note
note right of 销毁中
开始清理资源
end note

图表来源

• GFramework.Core/README.md

章节来源

• GFramework.Core/README.md

架构概览

GFramework的核心架构由Architecture基类提供统一的组件管理能力，支持模块化扩展和生命周期管理。

架构初始化流程

sequenceDiagram
participant Dev as 开发者
participant Arch as Architecture
participant Container as IoC容器
participant Utils as 工具组件
participant Models as 模型组件
participant Systems as 系统组件
Dev->>Arch : 创建架构实例
Dev->>Arch : Initialize()
Arch->>Arch : Init() (用户自定义)
Arch->>Container : 注册组件
Arch->>Utils : 初始化工具组件
Utils-->>Arch : 工具初始化完成
Arch->>Models : 初始化模型组件
Models-->>Arch : 模型初始化完成
Arch->>Systems : 初始化系统组件
Systems-->>Arch : 系统初始化完成
Arch->>Container : 冻结容器
Arch-->>Dev : 架构就绪

图表来源

• GFramework.Core/architecture/Architecture.cs

组件注册机制

架构提供统一的组件注册接口，支持系统、模型和工具的注册管理：

classDiagram
class Architecture {
+RegisterSystem(system)
+RegisterModel(model)
+RegisterUtility(utility)
+InstallModule(module)
+Initialize()
+Destroy()
-RegisterLifecycleComponent(component)
-ValidateRegistration(componentType)
}
class ISystem {
<<interface>>
+Init()
+Destroy()
+SetContext(context)
}
class IModel {
<<interface>>
+Init()
+SetContext(context)
}
class IUtility {
<<interface>>
+SetContext(context)
}
Architecture --> ISystem : 注册
Architecture --> IModel : 注册
Architecture --> IUtility : 注册
Architecture --> IIocContainer : 使用

图表来源

• GFramework.Core/architecture/Architecture.cs

章节来源

• GFramework.Core/architecture/Architecture.cs

详细组件分析

模型层 (Model)

模型层负责存储和管理游戏状态，采用响应式编程设计。

模型基类设计

classDiagram
class AbstractModel {
<<abstract>>
+Context : IArchitectureContext
+OnArchitecturePhase(phase)
#OnInit()
}
class IModel {
<<interface>>
+Init()
+SetContext(context)
}
class ContextAwareBase {
<<abstract>>
+Context : IArchitectureContext
+GetModel~T~()
+GetSystem~T~()
+GetUtility~T~()
+SendEvent(event)
+RegisterEvent~T~()
}
AbstractModel --|> ContextAwareBase
AbstractModel ..|> IModel
ContextAwareBase --> IArchitectureContext : 使用

图表来源

• GFramework.Core/model/AbstractModel.cs

响应式属性系统

可绑定属性提供自动化的数据变化通知机制：

flowchart TD
SetValue[设置属性值] --> Compare[比较新旧值]
Compare --> Equal{值相同?}
Equal --> |是| End[结束]
Equal --> |否| Update[更新内部值]
Update --> Trigger[触发回调事件]
Trigger --> End
subgraph "事件注册"
Register[注册回调]
RegisterWithInitValue[注册并立即调用]
UnRegister[取消注册]
end
Register --> Callback[存储回调]
RegisterWithInitValue --> Immediate[立即调用回调]
Immediate --> Callback
UnRegister --> Remove[移除回调]

图表来源

• GFramework.Core/property/BindableProperty.cs

章节来源

• GFramework.Core/model/AbstractModel.cs
• GFramework.Core/property/BindableProperty.cs

系统层 (System)

系统层处理业务逻辑，通过事件驱动实现组件间的松耦合通信。

系统生命周期管理

sequenceDiagram
participant Sys as System
participant Logger as 日志系统
participant Events as 事件系统
Sys->>Logger : 初始化日志记录器
Sys->>Sys : OnInit()
Sys->>Events : 注册事件监听
Sys-->>Logger : 系统初始化完成
Note over Sys : 运行时
Sys->>Events : 处理事件
Sys->>Sys : 更新业务状态
Sys->>Logger : 开始销毁
Sys->>Sys : OnDestroy()
Sys-->>Logger : 系统销毁完成

图表来源

• GFramework.Core/system/AbstractSystem.cs

章节来源

• GFramework.Core/system/AbstractSystem.cs

命令查询模式 (Command & Query)

GFramework采用CQRS模式分离读写操作，提供类型安全的命令和查询机制。

命令执行流程

flowchart TD
Start[开始执行命令] --> Validate[验证命令输入]
Validate --> InputValid{输入有效?}
InputValid --> |否| Error[返回错误]
InputValid --> |是| GetModels[获取所需模型]
GetModels --> ExecuteLogic[执行业务逻辑]
ExecuteLogic --> UpdateModels[更新模型状态]
UpdateModels --> SendEvents[发送相关事件]
SendEvents --> Complete[执行完成]
Error --> Complete

图表来源

• GFramework.Core/command/AbstractCommand.cs

查询执行流程

flowchart TD
QueryStart[开始执行查询] --> ValidateQuery[验证查询输入]
ValidateQuery --> InputValid{输入有效?}
InputValid --> |否| QueryError[返回默认值]
InputValid --> |是| GetModels[获取所需模型]
GetModels --> ExecuteQuery[执行查询逻辑]
ExecuteQuery --> ReturnResult[返回查询结果]
QueryError --> End[结束]
ReturnResult --> End

图表来源

• GFramework.Core/query/AbstractQuery.cs

章节来源

• GFramework.Core/command/AbstractCommand.cs
• GFramework.Core/query/AbstractQuery.cs

控制器层 (Controller)

控制器作为UI和业务逻辑之间的桥梁，负责处理用户输入和协调组件交互。

控制器设计模式

classDiagram
class IController {
<<interface>>
+Initialize()
+Cleanup()
}
class ContextAwareBase {
+Context : IArchitectureContext
+GetModel~T~()
+GetSystem~T~()
+GetUtility~T~()
+SendEvent(event)
+RegisterEvent~T~()
}
class IController {
<<interface>>
+Initialize()
+Cleanup()
}
ContextAwareBase --> IArchitectureContext : 使用
IController --|> ContextAwareBase

图表来源

• GFramework.Core/architecture/Architecture.cs

依赖关系分析

GFramework采用清晰的依赖层次结构，确保模块间的松耦合和高内聚。

项目依赖图

graph TB
subgraph "外部依赖"
DotNet[.NET 8/9]
NuGet[NuGet包管理器]
end
subgraph "核心框架"
Core[GFramework.Core]
CoreAbstraction[GFramework.Core.Abstractions]
end
subgraph "功能扩展"
Game[GFramework.Game]
GameAbstraction[GFramework.Game.Abstractions]
Godot[GFramework.Godot]
SourceGen[GFramework.SourceGenerators]
end
subgraph "测试"
CoreTests[GFramework.Core.Tests]
end
DotNet --> Core
NuGet --> Core
CoreAbstraction --> Core
Game --> Core
GameAbstraction --> Game
Godot --> Core
SourceGen --> Core
CoreTests --> Core

图表来源

• GFramework.Core/GFramework.Core.csproj
• GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj

组件间通信机制

graph LR
subgraph "事件驱动通信"
EventSystem[事件系统]
EventBus[IEventBus]
EventHandlers[事件处理器]
end
subgraph "依赖注入"
IoC[IoC容器]
Container[IIocContainer]
Services[架构服务]
end
subgraph "上下文管理"
Context[架构上下文]
ArchitectureContext[IArchitectureContext]
end
EventSystem --> EventBus
EventBus --> EventHandlers
IoC --> Container
Container --> Services
Services --> ArchitectureContext
ArchitectureContext --> Context

图表来源

• GFramework.Core/architecture/Architecture.cs

章节来源

• GFramework.Core/GFramework.Core.csproj
• GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj

性能考虑

GFramework在设计时充分考虑了性能优化，提供多种性能提升策略：

内存管理优化

• 对象池化: 通过AbstractNodePoolSystem实现Godot节点的高效复用
• 延迟初始化: 组件采用延迟初始化策略，减少启动时间
• 生命周期管理: 自动化的资源清理，防止内存泄漏

并发处理

• 异步初始化: 支持异步组件初始化，提高响应性
• 事件队列: 事件处理采用队列机制，避免阻塞主线程
• 批量操作: 支持批量注册和初始化操作

编译时优化

• 源码生成器: 通过源码生成器减少运行时开销
• 接口隔离: 小而专注的接口设计，减少不必要的依赖
• 泛型优化: 广泛使用泛型，提供类型安全的同时保持性能

故障排除指南

常见环境配置问题

.NET SDK安装问题

问题: dotnet命令不可用 解决方案:

1. 确认已安装.NET 8.0或更高版本
2. 重启开发环境使PATH生效
3. 运行dotnet --info验证安装

NuGet包引用问题

问题: 包安装失败或版本冲突 解决方案:

1. 清理NuGet缓存: dotnet nuget locals all --clear
2. 删除bin和obj文件夹
3. 重新还原包: dotnet restore

编译错误排查

类型不匹配错误

常见症状: 编译时报错提示类型不匹配 解决方法:

1. 检查接口实现是否完整
2. 确认泛型参数类型正确
3. 验证依赖项版本兼容性

依赖注入错误

常见症状: 运行时抛出依赖解析异常 解决方法:

1. 检查组件注册顺序
2. 确认构造函数参数正确
3. 验证模块安装时机

运行时问题诊断

事件未触发

排查步骤:

1. 检查事件注册是否在正确的生命周期阶段
2. 验证事件处理器是否正确实现
3. 确认事件类型匹配

组件初始化失败

排查步骤:

1. 查看架构初始化日志
2. 检查组件依赖关系
3. 验证上下文绑定状态

章节来源

• GFramework.Core/architecture/Architecture.cs
• GFramework.Core/architecture/Architecture.cs

结论

GFramework为游戏开发提供了一个完整、可扩展且高性能的架构解决方案。通过模块化设计和清晰的分层架构，开发者可以专注于游戏逻辑的实现，而无需担心底层基础设施的复杂性。

主要优势

• 平台无关: 核心模块可在任何.NET环境中运行
• 模块化设计: 支持按需组合和扩展功能模块
• 类型安全: 基于泛型的组件获取和事件系统
• 事件驱动: 松耦合的组件通信机制
• 生命周期管理: 自动化的组件初始化和清理

下一步建议

1. 从简单的游戏原型开始实践
2. 参考测试用例理解最佳实践
3. 根据项目需求选择合适的模块组合
4. 利用源码生成器提升开发效率

附录

快速开始模板

以下是一个最小化的GFramework项目模板：

// 1. 定义架构
public class MyGameArchitecture : Architecture
{
    protected override void Init()
    {
        RegisterModel(new GameStateModel());
        RegisterSystem(new GameStateSystem());
        RegisterUtility(new GameUtility());
    }
}

// 2. 定义模型
public class GameStateModel : AbstractModel
{
    public BindableProperty<int> Score { get; } = new(0);
    
    protected override void OnInit()
    {
        // 初始化逻辑
    }
}

// 3. 定义系统
public class GameStateSystem : AbstractSystem
{
    protected override void OnInit()
    {
        this.RegisterEvent<GameEvent>(OnGameEvent);
    }
    
    private void OnGameEvent(GameEvent e)
    {
        // 业务逻辑
    }
}

// 4. 初始化和运行
var architecture = new MyGameArchitecture();
architecture.Initialize();

测试验证清单

• 架构成功初始化
• 所有组件正确注册
• 事件系统正常工作
• 数据绑定功能正常
• 生命周期管理正确执行

项目打包建议

1. 配置适当的版本号和发布设置
2. 确保所有依赖项正确打包
3. 测试不同.NET版本的兼容性
4. 准备部署脚本和自动化流程