GFramework/.qoder/repowiki/zh/content/教程和指南/教程和指南.md

教程和指南

**本文引用的文件** - [README.md](file://README.md) - [Getting Started 教程](file://docs/tutorials/getting-started.md) - [Godot 集成教程](file://docs/tutorials/godot-integration.md) - [高级模式教程](file://docs/tutorials/advanced-patterns.md) - [架构模式最佳实践](file://docs/best-practices/architecture-patterns.md) - [GFramework.Core 概览](file://GFramework.Core/README.md) - [Architecture 包使用说明](file://GFramework.Core/architecture/README.md) - [Events 包使用说明](file://GFramework.Core/events/README.md) - [Command 包使用说明](file://GFramework.Core/command/README.md) - [Query 包使用说明](file://GFramework.Core/query/README.md) - [Property 包使用说明](file://GFramework.Core/property/README.md) - [IoC 包使用说明](file://GFramework.Core/ioc/README.md) - [GFramework.Godot 概览](file://GFramework.Godot/README.md) - [GFramework.SourceGenerators 概览](file://GFramework.SourceGenerators/README.md)

目录

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

引言

本教程面向希望使用 GFramework 从零开始开发游戏的开发者，提供从项目创建、架构设计、组件开发到部署发布的全流程指导。教程涵盖：

• 从零开始创建项目并配置工程结构
• 深入理解 GFramework 的核心架构与分层设计
• 使用 CQRS、事件驱动、模块化与状态机等高级模式
• 在 Godot 引擎中进行集成，包含节点生命周期绑定、信号系统、资源管理与性能优化
• 依赖注入、Clean Architecture、模块化开发策略
• 协程优化、事件系统调优、资源加载优化等性能技巧
• 常见问题与调试技巧

项目结构

GFramework 采用模块化设计，核心与平台解耦，Godot 集成在独立模块中，源码生成器提供编译时增强。

graph TB
subgraph "核心模块"
Core["GFramework.Core<br/>平台无关核心"]
Abstractions["GFramework.Core.Abstractions<br/>接口定义"]
Tests["GFramework.Core.Tests<br/>单元测试"]
end
subgraph "游戏层"
Game["GFramework.Game<br/>游戏特定抽象"]
GameAbstractions["GFramework.Game.Abstractions<br/>游戏接口"]
end
subgraph "Godot 集成"
Godot["GFramework.Godot<br/>Godot 特定实现"]
GodotSG["GFramework.Godot.SourceGenerators<br/>Godot 源码生成器"]
GodotSGAbstraction["GFramework.Godot.SourceGenerators.Abstractions"]
end
subgraph "源码生成器"
SG["GFramework.SourceGenerators<br/>通用源码生成器"]
SGAbstraction["GFramework.SourceGenerators.Abstractions"]
SGCommon["GFramework.SourceGenerators.Common"]
SGTests["GFramework.SourceGenerators.Tests"]
end
Core --> Abstractions
Game --> GameAbstractions
Godot --> Core
GodotSG --> Godot
SG --> Core
SGAbstraction --> SG

图表来源

• README.md
• GFramework.Core 概览

章节来源

• README.md
• GFramework.Core 概览

核心组件

• 架构与生命周期：通过 Architecture 管理组件注册、初始化与销毁，支持阶段式生命周期与模块化扩展。
• 事件系统：类型安全的事件总线，支持注册/注销、组合事件与架构生命周期事件。
• 命令与查询：CQRS 分离，命令用于写操作，查询用于读操作，二者通过事件解耦。
• 可绑定属性：响应式数据绑定，支持 UI 自动更新与属性监听。
• IoC 容器：轻量依赖注入容器，管理组件注册与获取。
• 源码生成器：零运行时开销的编译时代码生成，提供日志、上下文感知与枚举扩展。

章节来源

• Architecture 包使用说明
• Events 包使用说明
• Command 包使用说明
• Query 包使用说明
• Property 包使用说明
• IoC 包使用说明
• GFramework.SourceGenerators 概览

架构总览

GFramework 采用 Clean Architecture 风格的五层架构：View/UI、Controller、System、Model、Utility；横切关注点包括 Command/Query/Event。架构阶段包括初始化、Ready、Destroying、Destroyed 等阶段，支持模块安装与生命周期钩子。

graph TB
View["视图/UI"] --> Controller["控制器"]
Controller --> System["系统"]
System --> Model["模型"]
Model --> Utility["工具"]
Controller --> Command["命令"]
System --> Command
Model --> Command
Controller --> Query["查询"]
System --> Query
Model --> Query
Controller --> Event["事件"]
System --> Event
Model --> Event

图表来源

• GFramework.Core 概览
• Architecture 包使用说明

章节来源

• GFramework.Core 概览
• Architecture 包使用说明

详细组件分析

从零开始教程（含项目创建、架构设计、功能实现）

• 环境准备：.NET 6+、Godot 4.5.1+、IDE（Visual Studio、Rider、VS Code）
• 项目创建：Godot 项目 + C# 工程 + 模块化目录结构
• 架构设计：定义 GameArchitecture，注册 Model/System/Utility，安装模块
• 功能实现：主场景、玩家控制器、事件监听与数据绑定
• 测试验证：单元测试与集成测试
• 项目打包：发布与打包流程
• 进阶功能：UI 路由、过渡管线、设置系统

sequenceDiagram
participant Dev as "开发者"
participant Project as "Godot 项目"
participant Arch as "GameArchitecture"
participant Scene as "MainScene"
participant Ctrl as "PlayerController"
Dev->>Project : 创建项目与目录结构
Dev->>Arch : 定义架构并注册组件
Dev->>Scene : 初始化架构与创建游戏对象
Scene->>Ctrl : 注册事件监听
Ctrl->>Ctrl : 处理输入并发送事件
Ctrl->>Scene : 通过事件更新 UI

图表来源

• Getting Started 教程
• Getting Started 教程
• Getting Started 教程

章节来源

• Getting Started 教程
• Getting Started 教程
• Getting Started 教程
• Getting Started 教程

Godot 集成教程（节点生命周期、信号系统、资源管理、性能优化）

• 节点生命周期绑定：架构与 Godot 场景树同步，自动清理
• 模块系统：AudioModule、InputModule 等模块安装与生命周期
• 节点池化：BulletPoolSystem 的创建、回收与重用
• 信号系统：SignalBuilder 流畅 API、Godot 信号与框架事件桥接
• 资源管理：智能加载、预加载与卸载策略
• 性能优化：节点安全操作、异步加载、池化与事件优化

sequenceDiagram
participant Node as "Godot 节点"
participant Ext as "扩展方法"
participant Bus as "事件总线"
participant Sys as "系统"
participant UI as "UI"
Node->>Ext : 注册事件监听自动生命周期绑定
Ext->>Bus : 发送/接收事件
Bus->>Sys : 分发事件到系统
Sys->>UI : 更新 UI 或触发信号
UI-->>Node : 发送 Godot 信号

图表来源

• Godot 集成教程
• Godot 集成教程
• Godot 集成教程
• Godot 集成教程
• GFramework.Godot 概览
• GFramework.Godot 概览
• GFramework.Godot 概览
• GFramework.Godot 概览

章节来源

• Godot 集成教程
• Godot 集成教程
• Godot 集成教程
• Godot 集成教程
• GFramework.Godot 概览
• GFramework.Godot 概览
• GFramework.Godot 概览
• GFramework.Godot 概览

高级模式教程（CQRS、事件驱动、插件系统、状态机）

• CQRS：命令写操作、查询读操作、事件通知
• 事件溯源：事件存储、快照、聚合重建
• 事件总线：订阅/发布、异步处理、错误隔离
• 插件系统：模块化架构、模块安装与卸载
• 状态机：状态定义、状态转换、状态事件

flowchart TD
Start(["开始"]) --> DefineCmd["定义命令"]
DefineCmd --> ExecCmd["执行命令<br/>修改模型状态"]
ExecCmd --> SendEvt["发送领域事件"]
SendEvt --> HandleEvt["系统/控制器监听事件"]
HandleEvt --> UpdateUI["更新 UI 或触发信号"]
UpdateUI --> End(["结束"])
subgraph "查询路径"
QStart(["开始"]) --> SendQ["发送查询"]
SendQ --> ReadModel["读取模型状态"]
ReadModel --> ReturnQ["返回查询结果"]
ReturnQ --> QEnd(["结束"])
end

图表来源

• 高级模式教程
• 高级模式教程
• 高级模式教程
• Command 包使用说明
• Query 包使用说明

章节来源

• 高级模式教程
• 高级模式教程
• 高级模式教程
• 高级模式教程
• Command 包使用说明
• Query 包使用说明

架构模式最佳实践（Clean Architecture、依赖注入、模块化）

• 设计原则：SRP、OCP、DIP
• 分层架构：清晰的层次边界与职责
• 依赖管理：构造函数注入、接口隔离
• 事件系统设计：事件命名、职责单一
• 模块化架构：模块边界、模块间通信

classDiagram
class Architecture {
+RegisterModel()
+RegisterSystem()
+RegisterUtility()
+SendCommand()
+SendQuery()
+SendEvent()
}
class IocContainer {
+Register()
+Get()
+Freeze()
}
class EventBus {
+Register()
+Send()
}
class CommandBus {
+Send()
}
class QueryBus {
+Send()
}
Architecture --> IocContainer : "使用"
Architecture --> EventBus : "集成"
Architecture --> CommandBus : "集成"
Architecture --> QueryBus : "集成"

图表来源

• Architecture 包使用说明
• IoC 包使用说明
• Events 包使用说明
• Command 包使用说明
• Query 包使用说明

章节来源

• 架构模式最佳实践
• 架构模式最佳实践
• 架构模式最佳实践
• 架构模式最佳实践
• 架构模式最佳实践
• 架构模式最佳实践
• Architecture 包使用说明
• IoC 包使用说明
• Events 包使用说明
• Command 包使用说明
• Query 包使用说明

源码生成器（零运行时开销的代码增强）

• Log 属性生成器：自动生成 ILogger 字段与日志方法
• ContextAware 属性生成器：自动实现 IContextAware 接口
• GenerateEnumExtensions 属性生成器：为枚举生成扩展方法
• 诊断信息：编译时错误提示与修复建议
• 性能优势：零运行时开销、类型安全、内存分配优化

章节来源

• GFramework.SourceGenerators 概览
• GFramework.SourceGenerators 概览
• GFramework.SourceGenerators 概览
• GFramework.SourceGenerators 概览
• GFramework.SourceGenerators 概览

依赖分析

• 核心依赖：GFramework.Core 与 GFramework.Core.Abstractions 提供架构、事件、命令、查询、属性、IoC 等基础能力
• 平台集成：GFramework.Godot 提供与 Godot 的深度集成，包括节点扩展、信号系统、模块系统、资源管理与日志
• 源码生成：GFramework.SourceGenerators 与 GFramework.Godot.SourceGenerators 提供编译时代码生成能力

graph LR
Core["GFramework.Core"] --> Abstractions["GFramework.Core.Abstractions"]
Game["GFramework.Game"] --> GameAbstractions["GFramework.Game.Abstractions"]
Godot["GFramework.Godot"] --> Core
SG["GFramework.SourceGenerators"] --> Core
GodotSG["GFramework.Godot.SourceGenerators"] --> Godot

图表来源

• README.md
• GFramework.Core 概览

章节来源

• README.md
• GFramework.Core 概览

性能考虑

• 协程优化：使用 WaitUntil、WaitForFrames、WaitOneFrame 等 YieldInstruction 减少每帧开销
• 事件系统调优：避免每帧触发高频事件，使用结构体事件减少 GC 压力
• 资源加载优化：预加载、异步加载、资源缓存与按需卸载
• 节点池化：高频创建/销毁对象使用池化，降低内存碎片与 GC 压力
• 数据绑定：使用 BindableProperty 的 SetValueWithoutEvent 批量更新，最后统一触发事件

章节来源

• Property 包使用说明
• Events 包使用说明
• Godot 集成教程
• GFramework.Godot 概览

故障排除指南

• 事件未注销导致内存泄漏：使用 UnRegisterList 或 UnRegisterWhenNodeExitTree 自动清理
• 架构初始化失败：检查 Init() 中组件注册顺序与依赖关系，关注 FailedInitialization 阶段
• 源码生成器冲突：根据诊断信息（如 GF_Logging_001、GF_Rule_001、GF_Enum_001）修正属性使用与枚举命名
• Godot 节点访问异常：使用安全扩展方法（GetNodeX、FindChildX、AddChildX）避免空引用
• 性能问题排查：启用日志、使用生命周期钩子监控阶段耗时，定位瓶颈

章节来源

• Events 包使用说明
• Architecture 包使用说明
• GFramework.SourceGenerators 概览
• GFramework.Godot 概览

结论

本教程系统性地介绍了 GFramework 的从零开始开发流程、架构设计、高级模式与 Godot 集成实践，并提供了性能优化与故障排除指南。通过模块化与平台解耦的设计，开发者可以快速搭建高质量的游戏架构，同时在 Godot 引擎中发挥框架优势，实现高性能与可维护性的平衡。

附录

• API 参考：Core API、Godot API、Source Generators API、Game API
• 最佳实践：架构模式、性能优化技巧
• 常见问题：错误处理策略、调试技巧

章节来源

• README.md
• 架构模式最佳实践