mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-26 06:02:42 +08:00

GeWuYou a79f02c987 docs(api): 添加 Core API 参考文档与事件系统接口文档

- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件
- 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明
- 提供完整的 API 使用示例路径、最佳实践与性能建议
- 包含架构图、依赖关系图与故障排查指南
- 添加测试用例参考与扩展方法说明
- [skip ci]

2026-01-21 23:45:10 +08:00

16 KiB

Raw Blame History

迁移和升级指南

**本文档引用的文件** - [README.md](file://README.md) - [GFramework.Core/README.md](file://GFramework.Core/README.md) - [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/architecture/ArchitectureConfiguration.cs](file://GFramework.Core/architecture/ArchitectureConfiguration.cs) - [GFramework.Core/architecture/ArchitectureConstants.cs](file://GFramework.Core/architecture/ArchitectureConstants.cs) - [GFramework.Core/ioc/IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs) - [GFramework.Game/architecture/AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs) - [GFramework.Godot/architecture/AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs) - [GFramework.Godot/architecture/AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs) - [GFramework.Core/logging/ConsoleLoggerFactory.cs](file://GFramework.Core/logging/ConsoleLoggerFactory.cs) - [GFramework.SourceGenerators/README.md](file://GFramework.SourceGenerators/README.md) - [GFramework.Core.Tests/TEST_COVERAGE_PLAN.md](file://GFramework.Core.Tests/TEST_COVERAGE_PLAN.md)

简介

GFramework是一个专为游戏开发场景设计的综合性C#游戏开发框架，基于Clean Architecture原则构建，提供模块化、可扩展的架构解决方案。框架采用"约定优于配置"的设计理念，通过清晰的分层架构和强大的组件系统，为游戏开发提供了完整的基础设施。

主要特性

平台无关性：GFramework.Core是纯.NET库，可在任何.NET环境中运行
模块化设计：支持架构模块安装和扩展
生命周期管理：阶段式的架构生命周期管理
依赖注入：内置IoC容器管理对象生命周期
事件驱动：类型安全的事件系统实现松耦合
响应式编程：可绑定属性支持响应式数据流
源码生成器：零运行时开销的代码生成

项目结构

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/>源码生成器]
end
subgraph "测试"
Tests[GFramework.Core.Tests<br/>单元测试]
end
Core --> CoreAbstraction
Game --> Core
Game --> GameAbstraction
Godot --> Game
Godot --> CoreAbstraction
SourceGen --> Core
Tests --> Core

图表来源

章节来源

核心组件

架构系统

GFramework的核心是Architecture类，它作为整个应用的"中央调度器"，负责管理所有组件的生命周期和注册。

classDiagram
class Architecture {
+Initialize() void
+InitializeAsync() Task
+RegisterModel~T~(model) T
+RegisterSystem~T~(system) T
+RegisterUtility~T~(utility) T
+InstallModule(module) IArchitectureModule
+Destroy() void
-Init() void
-EnterPhase(next) void
-ValidatePhaseTransition(next) void
}
class IArchitecture {
<<interface>>
+Initialize() void
+InitializeAsync() Task
+RegisterModel~T~(model) T
+RegisterSystem~T~(system) T
+RegisterUtility~T~(utility) T
+InstallModule(module) IArchitectureModule
+Destroy() void
}
class ArchitectureConfiguration {
+LoggerProperties LoggerProperties
+ArchitectureProperties ArchitectureProperties
}
class ArchitectureConstants {
+PhaseOrder ArchitecturePhase[]
+PhaseTransitions ImmutableDictionary
}
Architecture ..|> IArchitecture
Architecture --> ArchitectureConfiguration
Architecture --> ArchitectureConstants

图表来源

依赖注入容器

IocContainer提供线程安全的依赖注入功能，支持单例和多重注册：

classDiagram
class IocContainer {
-ReaderWriterLockSlim lock
-bool _frozen
-HashSet~object~ _objects
-Dictionary~Type, HashSet~object~~ _typeIndex
+RegisterSingleton~T~(instance) void
+RegisterPlurality(instance) void
+Register~T~(instance) void
+Get~T~() T?
+GetRequired~T~() T
+GetAll~T~() IReadOnlyList~T~
+Contains~T~() bool
+Freeze() void
}
class IIocContainer {
<<interface>>
+RegisterSingleton~T~(instance) void
+RegisterPlurality(instance) void
+Get~T~() T?
+GetRequired~T~() T
+GetAll~T~() IReadOnlyList~T~
+Contains~T~() bool
+Freeze() void
}
IocContainer ..|> IIocContainer

图表来源

GFramework.Core/ioc/IocContainer.cs

章节来源

架构概览

五层架构设计

GFramework遵循Clean Architecture原则，采用清晰的分层架构：

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

图表来源

GFramework.Core/README.md

架构阶段流程

sequenceDiagram
participant App as 应用程序
participant Arch as Architecture
participant Utils as 工具组件
participant Models as 模型组件
participant Systems as 系统组件
App->>Arch : Initialize()
Arch->>Arch : Init()
Arch->>Utils : RegisterSystem()
Utils->>Utils : SetContext()
Utils->>Utils : Init()
Arch->>Models : RegisterModel()
Models->>Models : SetContext()
Models->>Models : Init()
Arch->>Systems : RegisterSystem()
Systems->>Systems : SetContext()
Systems->>Systems : Init()
Arch->>Arch : Freeze Container
Arch->>Arch : Enter Ready Phase
Arch-->>App : Architecture Ready

图表来源

GFramework.Core/architecture/Architecture.cs

章节来源

GFramework.Core/README.md

详细组件分析

模块系统

GFramework提供灵活的模块化架构，支持游戏功能的模块化扩展：

classDiagram
class IArchitectureModule {
<<interface>>
+Install(IArchitecture) void
+OnPhase(ArchitecturePhase, IArchitecture) void
+OnArchitecturePhase(ArchitecturePhase) void
}
class AbstractModule {
+Install(IArchitecture) void
+OnPhase(ArchitecturePhase, IArchitecture) void
+OnArchitecturePhase(ArchitecturePhase) void
}
class AbstractGodotModule {
+Node Node
+Install(IArchitecture) void
+OnPhase(ArchitecturePhase, IArchitecture) void
+OnAttach(Architecture) void
+OnDetach() void
}
IArchitectureModule <|.. AbstractModule
AbstractModule <|-- AbstractGodotModule

图表来源

数据迁移系统

GFramework提供完整的数据迁移和版本管理功能：

flowchart TD
Start([开始迁移]) --> CheckVersion["检查当前版本"]
CheckVersion --> CompareVersion{"版本比较"}
CompareVersion --> |需要迁移| FindMigration["查找迁移器"]
CompareVersion --> |无需迁移| Complete["迁移完成"]
FindMigration --> ApplyMigration["应用迁移"]
ApplyMigration --> UpdateVersion["更新版本信息"]
UpdateVersion --> NextVersion{"还有版本需要迁移?"}
NextVersion --> |是| FindMigration
NextVersion --> |否| Complete
Complete --> End([结束])

图表来源

GFramework.Game/README.md

章节来源

日志系统

GFramework提供灵活的日志配置和管理功能：

classDiagram
class ILoggerFactory {
<<interface>>
+GetLogger(name, minLevel) ILogger
}
class ConsoleLoggerFactory {
+GetLogger(name, minLevel) ILogger
}
class ArchitectureConfiguration {
+LoggerProperties LoggerProperties
}
class LoggerProperties {
+ILoggerFactoryProvider LoggerFactoryProvider
+LogLevel MinLevel
}
ILoggerFactory <|.. ConsoleLoggerFactory
ArchitectureConfiguration --> LoggerProperties

图表来源

GFramework.Core/logging/ConsoleLoggerFactory.cs

章节来源

GFramework.Core/logging/ConsoleLoggerFactory.cs

依赖分析

组件耦合关系

graph LR
subgraph "核心依赖"
CoreAbstraction[GFramework.Core.Abstractions]
Core[GFramework.Core]
end
subgraph "游戏功能"
GameAbstraction[GFramework.Game.Abstractions]
Game[GFramework.Game]
end
subgraph "平台集成"
GodotAbstraction[GFramework.Core.Abstractions]
Godot[GFramework.Godot]
end
subgraph "源码生成"
SourceGenAbstraction[GFramework.SourceGenerators.Abstractions]
SourceGen[GFramework.SourceGenerators]
end
CoreAbstraction --> Core
GameAbstraction --> Game
GodotAbstraction --> Godot
SourceGenAbstraction --> SourceGen
Game --> Core
Godot --> Game
Godot --> CoreAbstraction
SourceGen --> Core

图表来源

版本兼容性矩阵

组件	.NET 8.0	.NET 9.0	.NET 10.0
GFramework.Core	✓	✓	✓
GFramework.Game	✓	✓	✓
GFramework.Godot	✓	✓	✓
GFramework.SourceGenerators	✓	✓	✓

章节来源

性能考虑

内存管理

GFramework通过以下机制优化内存使用：

对象池化：支持对象池系统减少垃圾回收压力
延迟初始化：上下文和日志记录器的延迟初始化
线程安全：使用ReaderWriterLockSlim优化并发访问
容器冻结：初始化后冻结IoC容器防止意外修改

性能优化建议

flowchart TD
Start([性能优化开始]) --> Profile["性能分析"]
Profile --> IdentifyBottlenecks["识别瓶颈"]
IdentifyBottlenecks --> OptimizeMemory["内存优化"]
OptimizeMemory --> OptimizeCPU["CPU优化"]
OptimizeCPU --> Test["测试验证"]
Test --> Profile
OptimizeMemory --> Pooling["对象池化"]
OptimizeMemory --> LazyInit["延迟初始化"]
OptimizeMemory --> ReadOnlyStructs["只读结构体"]
OptimizeCPU --> AsyncOps["异步操作"]
OptimizeCPU --> Caching["缓存策略"]
OptimizeCPU --> BatchOps["批量操作"]

章节来源

GFramework.Core/ioc/IocContainer.cs

故障排除指南

常见问题诊断

架构初始化失败

症状：架构初始化抛出InvalidOperationException

可能原因：

组件注册时机错误（在Ready阶段后注册）
重复注册单例
依赖注入循环

解决方案：

// 检查架构配置
var config = new ArchitectureConfiguration();
config.ArchitectureProperties.AllowLateRegistration = true; // 临时解决方案

// 验证组件注册顺序
architecture.RegisterUtility(myUtility);
architecture.RegisterModel(myModel);
architecture.RegisterSystem(mySystem);

模块安装问题

症状：模块安装后无法正常工作

排查步骤：

检查模块是否正确实现Install方法
验证模块生命周期回调
确认模块依赖关系

章节来源

测试和验证

单元测试策略

根据测试覆盖计划，建议重点关注以下区域：

异步功能测试：CommandBus、AbstractAsyncCommand、AsyncQueryBus、AbstractAsyncQuery
工具基类测试：AbstractContextUtility
常量验证测试：ArchitectureConstants、GFrameworkConstants

章节来源

GFramework.Core.Tests/TEST_COVERAGE_PLAN.md

结论

GFramework提供了一个完整、模块化且高度可扩展的游戏开发框架。通过清晰的分层架构、强大的组件系统和灵活的模块化设计，开发者可以快速构建高质量的游戏应用。

主要优势

架构清晰：遵循Clean Architecture原则，职责分离明确
扩展性强：模块化设计支持功能扩展和平台移植
性能优秀：零运行时开销的源码生成器和优化的内存管理
开发效率：丰富的工具和最佳实践减少开发成本

未来发展方向

持续测试改进：完善异步功能的单元测试覆盖
平台扩展：支持更多游戏引擎和平台
性能优化：进一步优化内存使用和执行效率
文档完善：持续更新API文档和最佳实践指南

附录

迁移检查清单

从旧版本升级

备份项目：创建完整的项目备份
检查依赖：确认.NET版本兼容性
更新包引用：升级到最新版本的GFramework包
测试功能：验证核心功能正常运行
性能测试：运行性能基准测试

从其他框架迁移

分析现有架构：识别现有的组件和数据结构
设计迁移策略：制定逐步迁移计划
创建映射层：实现新旧框架的兼容层
数据迁移：安全地迁移游戏数据
功能验证：确保所有功能正常工作

自定义扩展开发

创建模块：继承AbstractModule或AbstractGodotModule
实现接口：遵循GFramework的接口约定
注册组件：在Install方法中注册所需组件
测试验证：编写单元测试验证功能
文档编写：为新模块编写使用文档

16 KiB Raw Blame History Unescape Escape

迁移和升级指南

目录

简介

主要特性

项目结构

核心组件

架构系统

依赖注入容器

架构概览

五层架构设计

架构阶段流程

详细组件分析

模块系统

数据迁移系统

日志系统

依赖分析

组件耦合关系

版本兼容性矩阵

性能考虑

内存管理

性能优化建议

故障排除指南

常见问题诊断

架构初始化失败

模块安装问题

测试和验证

单元测试策略

结论

主要优势

未来发展方向

附录

迁移检查清单

从旧版本升级

从其他框架迁移

自定义扩展开发

16 KiB

Raw Blame History