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]
376 lines
17 KiB
Markdown
376 lines
17 KiB
Markdown
# 教程和指南
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [引言](#引言)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 引言
|
||
本教程面向希望使用 GFramework 从零开始开发游戏的开发者，提供从项目创建、架构设计、组件开发到部署发布的全流程指导。教程涵盖：
|
||
- 从零开始创建项目并配置工程结构
|
||
- 深入理解 GFramework 的核心架构与分层设计
|
||
- 使用 CQRS、事件驱动、模块化与状态机等高级模式
|
||
- 在 Godot 引擎中进行集成，包含节点生命周期绑定、信号系统、资源管理与性能优化
|
||
- 依赖注入、Clean Architecture、模块化开发策略
|
||
- 协程优化、事件系统调优、资源加载优化等性能技巧
|
||
- 常见问题与调试技巧
|
||
|
||
## 项目结构
|
||
GFramework 采用模块化设计，核心与平台解耦，Godot 集成在独立模块中，源码生成器提供编译时增强。
|
||
|
||
```mermaid
|
||
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](file://README.md#L31-L51)
|
||
- [GFramework.Core 概览](file://GFramework.Core/README.md#L285-L304)
|
||
|
||
章节来源
|
||
- [README.md](file://README.md#L31-L51)
|
||
- [GFramework.Core 概览](file://GFramework.Core/README.md#L285-L304)
|
||
|
||
## 核心组件
|
||
- 架构与生命周期：通过 Architecture 管理组件注册、初始化与销毁，支持阶段式生命周期与模块化扩展。
|
||
- 事件系统：类型安全的事件总线，支持注册/注销、组合事件与架构生命周期事件。
|
||
- 命令与查询：CQRS 分离，命令用于写操作，查询用于读操作，二者通过事件解耦。
|
||
- 可绑定属性：响应式数据绑定，支持 UI 自动更新与属性监听。
|
||
- IoC 容器：轻量依赖注入容器，管理组件注册与获取。
|
||
- 源码生成器：零运行时开销的编译时代码生成，提供日志、上下文感知与枚举扩展。
|
||
|
||
章节来源
|
||
- [Architecture 包使用说明](file://GFramework.Core/architecture/README.md#L80-L143)
|
||
- [Events 包使用说明](file://GFramework.Core/events/README.md#L52-L163)
|
||
- [Command 包使用说明](file://GFramework.Core/command/README.md#L29-L84)
|
||
- [Query 包使用说明](file://GFramework.Core/query/README.md#L20-L66)
|
||
- [Property 包使用说明](file://GFramework.Core/property/README.md#L43-L99)
|
||
- [IoC 包使用说明](file://GFramework.Core/ioc/README.md#L10-L47)
|
||
- [GFramework.SourceGenerators 概览](file://GFramework.SourceGenerators/README.md#L32-L46)
|
||
|
||
## 架构总览
|
||
GFramework 采用 Clean Architecture 风格的五层架构：View/UI、Controller、System、Model、Utility；横切关注点包括 Command/Query/Event。架构阶段包括初始化、Ready、Destroying、Destroyed 等阶段，支持模块安装与生命周期钩子。
|
||
|
||
```mermaid
|
||
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 概览](file://GFramework.Core/README.md#L42-L64)
|
||
- [Architecture 包使用说明](file://GFramework.Core/architecture/README.md#L107-L124)
|
||
|
||
章节来源
|
||
- [GFramework.Core 概览](file://GFramework.Core/README.md#L42-L64)
|
||
- [Architecture 包使用说明](file://GFramework.Core/architecture/README.md#L107-L124)
|
||
|
||
## 详细组件分析
|
||
|
||
### 从零开始教程（含项目创建、架构设计、功能实现）
|
||
- 环境准备：.NET 6+、Godot 4.5.1+、IDE（Visual Studio、Rider、VS Code）
|
||
- 项目创建：Godot 项目 + C# 工程 + 模块化目录结构
|
||
- 架构设计：定义 GameArchitecture，注册 Model/System/Utility，安装模块
|
||
- 功能实现：主场景、玩家控制器、事件监听与数据绑定
|
||
- 测试验证：单元测试与集成测试
|
||
- 项目打包：发布与打包流程
|
||
- 进阶功能：UI 路由、过渡管线、设置系统
|
||
|
||
```mermaid
|
||
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 教程](file://docs/tutorials/getting-started.md#L59-L137)
|
||
- [Getting Started 教程](file://docs/tutorials/getting-started.md#L165-L207)
|
||
- [Getting Started 教程](file://docs/tutorials/getting-started.md#L480-L642)
|
||
|
||
章节来源
|
||
- [Getting Started 教程](file://docs/tutorials/getting-started.md#L15-L16)
|
||
- [Getting Started 教程](file://docs/tutorials/getting-started.md#L59-L137)
|
||
- [Getting Started 教程](file://docs/tutorials/getting-started.md#L165-L207)
|
||
- [Getting Started 教程](file://docs/tutorials/getting-started.md#L480-L642)
|
||
|
||
### Godot 集成教程（节点生命周期、信号系统、资源管理、性能优化）
|
||
- 节点生命周期绑定：架构与 Godot 场景树同步，自动清理
|
||
- 模块系统：AudioModule、InputModule 等模块安装与生命周期
|
||
- 节点池化：BulletPoolSystem 的创建、回收与重用
|
||
- 信号系统：SignalBuilder 流畅 API、Godot 信号与框架事件桥接
|
||
- 资源管理：智能加载、预加载与卸载策略
|
||
- 性能优化：节点安全操作、异步加载、池化与事件优化
|
||
|
||
```mermaid
|
||
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 集成教程](file://docs/tutorials/godot-integration.md#L15-L114)
|
||
- [Godot 集成教程](file://docs/tutorials/godot-integration.md#L173-L290)
|
||
- [Godot 集成教程](file://docs/tutorials/godot-integration.md#L336-L421)
|
||
- [Godot 集成教程](file://docs/tutorials/godot-integration.md#L520-L695)
|
||
- [GFramework.Godot 概览](file://GFramework.Godot/README.md#L66-L142)
|
||
- [GFramework.Godot 概览](file://GFramework.Godot/README.md#L199-L331)
|
||
- [GFramework.Godot 概览](file://GFramework.Godot/README.md#L332-L416)
|
||
- [GFramework.Godot 概览](file://GFramework.Godot/README.md#L418-L490)
|
||
|
||
章节来源
|
||
- [Godot 集成教程](file://docs/tutorials/godot-integration.md#L15-L114)
|
||
- [Godot 集成教程](file://docs/tutorials/godot-integration.md#L173-L290)
|
||
- [Godot 集成教程](file://docs/tutorials/godot-integration.md#L336-L421)
|
||
- [Godot 集成教程](file://docs/tutorials/godot-integration.md#L520-L695)
|
||
- [GFramework.Godot 概览](file://GFramework.Godot/README.md#L66-L142)
|
||
- [GFramework.Godot 概览](file://GFramework.Godot/README.md#L199-L331)
|
||
- [GFramework.Godot 概览](file://GFramework.Godot/README.md#L332-L416)
|
||
- [GFramework.Godot 概览](file://GFramework.Godot/README.md#L418-L490)
|
||
|
||
### 高级模式教程（CQRS、事件驱动、插件系统、状态机）
|
||
- CQRS：命令写操作、查询读操作、事件通知
|
||
- 事件溯源：事件存储、快照、聚合重建
|
||
- 事件总线：订阅/发布、异步处理、错误隔离
|
||
- 插件系统：模块化架构、模块安装与卸载
|
||
- 状态机：状态定义、状态转换、状态事件
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [高级模式教程](file://docs/tutorials/advanced-patterns.md#L17-L206)
|
||
- [高级模式教程](file://docs/tutorials/advanced-patterns.md#L515-L690)
|
||
- [高级模式教程](file://docs/tutorials/advanced-patterns.md#L692-L800)
|
||
- [Command 包使用说明](file://GFramework.Core/command/README.md#L150-L174)
|
||
- [Query 包使用说明](file://GFramework.Core/query/README.md#L50-L66)
|
||
|
||
章节来源
|
||
- [高级模式教程](file://docs/tutorials/advanced-patterns.md#L15-L14)
|
||
- [高级模式教程](file://docs/tutorials/advanced-patterns.md#L17-L206)
|
||
- [高级模式教程](file://docs/tutorials/advanced-patterns.md#L515-L690)
|
||
- [高级模式教程](file://docs/tutorials/advanced-patterns.md#L692-L800)
|
||
- [Command 包使用说明](file://GFramework.Core/command/README.md#L150-L174)
|
||
- [Query 包使用说明](file://GFramework.Core/query/README.md#L50-L66)
|
||
|
||
### 架构模式最佳实践（Clean Architecture、依赖注入、模块化）
|
||
- 设计原则：SRP、OCP、DIP
|
||
- 分层架构：清晰的层次边界与职责
|
||
- 依赖管理：构造函数注入、接口隔离
|
||
- 事件系统设计：事件命名、职责单一
|
||
- 模块化架构：模块边界、模块间通信
|
||
|
||
```mermaid
|
||
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 包使用说明](file://GFramework.Core/architecture/README.md#L80-L143)
|
||
- [IoC 包使用说明](file://GFramework.Core/ioc/README.md#L10-L47)
|
||
- [Events 包使用说明](file://GFramework.Core/events/README.md#L138-L163)
|
||
- [Command 包使用说明](file://GFramework.Core/command/README.md#L150-L174)
|
||
- [Query 包使用说明](file://GFramework.Core/query/README.md#L50-L66)
|
||
|
||
章节来源
|
||
- [架构模式最佳实践](file://docs/best-practices/architecture-patterns.md#L16-L88)
|
||
- [架构模式最佳实践](file://docs/best-practices/architecture-patterns.md#L284-L464)
|
||
- [架构模式最佳实践](file://docs/best-practices/architecture-patterns.md#L466-L576)
|
||
- [架构模式最佳实践](file://docs/best-practices/architecture-patterns.md#L578-L688)
|
||
- [架构模式最佳实践](file://docs/best-practices/architecture-patterns.md#L689-L745)
|
||
- [架构模式最佳实践](file://docs/best-practices/architecture-patterns.md#L747-L800)
|
||
- [Architecture 包使用说明](file://GFramework.Core/architecture/README.md#L80-L143)
|
||
- [IoC 包使用说明](file://GFramework.Core/ioc/README.md#L10-L47)
|
||
- [Events 包使用说明](file://GFramework.Core/events/README.md#L138-L163)
|
||
- [Command 包使用说明](file://GFramework.Core/command/README.md#L150-L174)
|
||
- [Query 包使用说明](file://GFramework.Core/query/README.md#L50-L66)
|
||
|
||
### 源码生成器（零运行时开销的代码增强）
|
||
- Log 属性生成器：自动生成 ILogger 字段与日志方法
|
||
- ContextAware 属性生成器：自动实现 IContextAware 接口
|
||
- GenerateEnumExtensions 属性生成器：为枚举生成扩展方法
|
||
- 诊断信息：编译时错误提示与修复建议
|
||
- 性能优势：零运行时开销、类型安全、内存分配优化
|
||
|
||
章节来源
|
||
- [GFramework.SourceGenerators 概览](file://GFramework.SourceGenerators/README.md#L80-L177)
|
||
- [GFramework.SourceGenerators 概览](file://GFramework.SourceGenerators/README.md#L178-L282)
|
||
- [GFramework.SourceGenerators 概览](file://GFramework.SourceGenerators/README.md#L283-L422)
|
||
- [GFramework.SourceGenerators 概览](file://GFramework.SourceGenerators/README.md#L434-L564)
|
||
- [GFramework.SourceGenerators 概览](file://GFramework.SourceGenerators/README.md#L566-L717)
|
||
|
||
## 依赖分析
|
||
- 核心依赖：GFramework.Core 与 GFramework.Core.Abstractions 提供架构、事件、命令、查询、属性、IoC 等基础能力
|
||
- 平台集成：GFramework.Godot 提供与 Godot 的深度集成，包括节点扩展、信号系统、模块系统、资源管理与日志
|
||
- 源码生成：GFramework.SourceGenerators 与 GFramework.Godot.SourceGenerators 提供编译时代码生成能力
|
||
|
||
```mermaid
|
||
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](file://README.md#L33-L51)
|
||
- [GFramework.Core 概览](file://GFramework.Core/README.md#L285-L304)
|
||
|
||
章节来源
|
||
- [README.md](file://README.md#L33-L51)
|
||
- [GFramework.Core 概览](file://GFramework.Core/README.md#L285-L304)
|
||
|
||
## 性能考虑
|
||
- 协程优化：使用 WaitUntil、WaitForFrames、WaitOneFrame 等 YieldInstruction 减少每帧开销
|
||
- 事件系统调优：避免每帧触发高频事件，使用结构体事件减少 GC 压力
|
||
- 资源加载优化：预加载、异步加载、资源缓存与按需卸载
|
||
- 节点池化：高频创建/销毁对象使用池化，降低内存碎片与 GC 压力
|
||
- 数据绑定：使用 BindableProperty 的 SetValueWithoutEvent 批量更新，最后统一触发事件
|
||
|
||
章节来源
|
||
- [Property 包使用说明](file://GFramework.Core/property/README.md#L278-L302)
|
||
- [Events 包使用说明](file://GFramework.Core/events/README.md#L507-L515)
|
||
- [Godot 集成教程](file://docs/tutorials/godot-integration.md#L796-L800)
|
||
- [GFramework.Godot 概览](file://GFramework.Godot/README.md#L51-L55)
|
||
|
||
## 故障排除指南
|
||
- 事件未注销导致内存泄漏：使用 UnRegisterList 或 UnRegisterWhenNodeExitTree 自动清理
|
||
- 架构初始化失败：检查 Init() 中组件注册顺序与依赖关系，关注 FailedInitialization 阶段
|
||
- 源码生成器冲突：根据诊断信息（如 GF_Logging_001、GF_Rule_001、GF_Enum_001）修正属性使用与枚举命名
|
||
- Godot 节点访问异常：使用安全扩展方法（GetNodeX、FindChildX、AddChildX）避免空引用
|
||
- 性能问题排查：启用日志、使用生命周期钩子监控阶段耗时，定位瓶颈
|
||
|
||
章节来源
|
||
- [Events 包使用说明](file://GFramework.Core/events/README.md#L437-L475)
|
||
- [Architecture 包使用说明](file://GFramework.Core/architecture/README.md#L227-L230)
|
||
- [GFramework.SourceGenerators 概览](file://GFramework.SourceGenerators/README.md#L434-L513)
|
||
- [GFramework.Godot 概览](file://GFramework.Godot/README.md#L203-L238)
|
||
|
||
## 结论
|
||
本教程系统性地介绍了 GFramework 的从零开始开发流程、架构设计、高级模式与 Godot 集成实践，并提供了性能优化与故障排除指南。通过模块化与平台解耦的设计，开发者可以快速搭建高质量的游戏架构，同时在 Godot 引擎中发挥框架优势，实现高性能与可维护性的平衡。
|
||
|
||
## 附录
|
||
- API 参考：Core API、Godot API、Source Generators API、Game API
|
||
- 最佳实践：架构模式、性能优化技巧
|
||
- 常见问题：错误处理策略、调试技巧
|
||
|
||
章节来源
|
||
- [README.md](file://README.md#L47-L59)
|
||
- [架构模式最佳实践](file://docs/best-practices/architecture-patterns.md#L1-L14) |