# 从零开始教程

<cite>
**本文档引用的文件**
- [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)
</cite>

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

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

## 项目结构
GFramework采用模块化设计，主要包含以下核心模块：

```mermaid
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](file://GFramework.Core/GFramework.Core.csproj#L1-L13)
- [GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj](file://GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj#L1-L29)

**章节来源**
- [README.md](file://README.md#L1-L320)
- [GFramework.Core/README.md](file://GFramework.Core/README.md#L1-L508)

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

### 五层架构设计
```mermaid
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](file://GFramework.Core/README.md#L42-L108)

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

```mermaid
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](file://GFramework.Core/README.md#L66-L71)

**章节来源**
- [GFramework.Core/README.md](file://GFramework.Core/README.md#L40-L108)

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

### 架构初始化流程
```mermaid
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](file://GFramework.Core/architecture/Architecture.cs#L526-L566)

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

```mermaid
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](file://GFramework.Core/architecture/Architecture.cs#L416-L483)

**章节来源**
- [GFramework.Core/architecture/Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)

## 详细组件分析

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

#### 模型基类设计
```mermaid
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](file://GFramework.Core/model/AbstractModel.cs#L11-L34)

#### 响应式属性系统
可绑定属性提供自动化的数据变化通知机制：

```mermaid
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](file://GFramework.Core/property/BindableProperty.cs#L24-L87)

**章节来源**
- [GFramework.Core/model/AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs#L1-L34)
- [GFramework.Core/property/BindableProperty.cs](file://GFramework.Core/property/BindableProperty.cs#L1-L135)

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

#### 系统生命周期管理
```mermaid
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](file://GFramework.Core/system/AbstractSystem.cs#L20-L41)

**章节来源**
- [GFramework.Core/system/AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs#L1-L62)

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

#### 命令执行流程
```mermaid
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](file://GFramework.Core/command/AbstractCommand.cs#L17-L26)

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

**图表来源**
- [GFramework.Core/query/AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L18-L28)

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

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

#### 控制器设计模式
```mermaid
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](file://GFramework.Core/architecture/Architecture.cs#L23-L28)

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

### 项目依赖图
```mermaid
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](file://GFramework.Core/GFramework.Core.csproj#L1-L13)
- [GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj](file://GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj#L1-L29)

### 组件间通信机制
```mermaid
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](file://GFramework.Core/architecture/Architecture.cs#L72-L87)

**章节来源**
- [GFramework.Core/GFramework.Core.csproj](file://GFramework.Core/GFramework.Core.csproj#L1-L13)
- [GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj](file://GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj#L1-L29)

## 性能考虑
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](file://GFramework.Core/architecture/Architecture.cs#L164-L183)
- [GFramework.Core/architecture/Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L357-L396)

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

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

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

## 附录

### 快速开始模板
以下是一个最小化的GFramework项目模板：

```csharp
// 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. 准备部署脚本和自动化流程