# 最佳实践指南

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [GFramework.Core/README.md](file://GFramework.Core/README.md)
- [GFramework.Core.Abstractions/README.md](file://GFramework.Core.Abstractions/README.md)
- [GFramework.Game/README.md](file://GFramework.Game/README.md)
- [GFramework.Godot/README.md](file://GFramework.Godot/README.md)
- [docs/best-practices/architecture-patterns.md](file://docs/best-practices/architecture-patterns.md)
- [GFramework.Core/architecture/Architecture.cs](file://GFramework.Core/architecture/Architecture.cs)
- [GFramework.Core/ioc/IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs)
- [GFramework.Core/events/EventBus.cs](file://GFramework.Core/events/EventBus.cs)
- [GFramework.Core/command/CommandBus.cs](file://GFramework.Core/command/CommandBus.cs)
- [GFramework.Core/query/QueryBus.cs](file://GFramework.Core/query/QueryBus.cs)
- [GFramework.Core/coroutine/CoroutineScheduler.cs](file://GFramework.Core/coroutine/CoroutineScheduler.cs)
- [GFramework.Core/logging/ConsoleLogger.cs](file://GFramework.Core/logging/ConsoleLogger.cs)
- [GFramework.Game/storage/FileStorage.cs](file://GFramework.Game/storage/FileStorage.cs)
- [GFramework.Godot/coroutine/GodotTimeSource.cs](file://GFramework.Godot/coroutine/GodotTimeSource.cs)
</cite>

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

## 简介
本指南面向使用 GFramework 的游戏开发团队，系统阐述 Clean Architecture 在游戏开发中的应用方法，涵盖分层架构设计原则、依赖注入正确使用、模块化开发策略、性能优化技巧、代码组织与命名规范、错误处理与调试方法，以及团队协作与代码审查建议。文档基于仓库中的核心实现与最佳实践文档，提供可操作的指导与可视化说明。

## 项目结构
GFramework 采用多模块分层设计，核心模块与平台集成模块分离，既保证了平台无关性，又为 Godot 等平台提供深度集成能力。

```mermaid
graph TB
subgraph "核心层"
Core["GFramework.Core<br/>平台无关核心"]
CoreAbst["GFramework.Core.Abstractions<br/>抽象契约"]
end
subgraph "游戏层"
Game["GFramework.Game<br/>游戏特定抽象"]
GameAbst["GFramework.Game.Abstractions<br/>游戏抽象接口"]
end
subgraph "平台集成"
Godot["GFramework.Godot<br/>Godot集成"]
GodotSrcGen["GFramework.Godot.SourceGenerators<br/>Godot源码生成器"]
end
subgraph "源码生成器"
SrcGen["GFramework.SourceGenerators<br/>通用源码生成器"]
SrcGenAbst["GFramework.SourceGenerators.Abstractions<br/>生成器抽象"]
SrcGenCommon["GFramework.SourceGenerators.Common<br/>生成器公共库"]
end
Core --> CoreAbst
Game --> GameAbst
Godot --> Core
Godot --> CoreAbst
SrcGen --> CoreAbst
SrcGenAbst --> CoreAbst
SrcGenCommon --> CoreAbst
GodotSrcGen --> Godot
```

**图表来源**
- [README.md](file://README.md#L235-L254)
- [GFramework.Core/README.md](file://GFramework.Core/README.md#L73-L109)

**章节来源**
- [README.md](file://README.md#L235-L254)
- [GFramework.Core/README.md](file://GFramework.Core/README.md#L73-L109)

## 核心组件
本节聚焦 GFramework 的核心基础设施：架构生命周期管理、依赖注入容器、事件总线、命令/查询总线、协程调度器与日志系统。

- 架构生命周期管理：负责组件注册、初始化阶段推进、销毁流程与阶段感知通知。
- 依赖注入容器：提供注册、解析、冻结与线程安全的实例管理。
- 事件总线：基于类型的事件发布/订阅，支持注册/注销与统一注销列表。
- 命令/查询总线：封装写操作与读操作，支持同步与异步执行。
- 协程调度器：基于时间源的协程执行与等待机制，支持暂停/恢复/终止与标签管理。
- 日志系统：控制台日志记录器，支持级别与彩色输出。

**章节来源**
- [GFramework.Core/architecture/Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L135-L398)
- [GFramework.Core/ioc/IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L9-L373)
- [GFramework.Core/events/EventBus.cs](file://GFramework.Core/events/EventBus.cs#L1-L55)
- [GFramework.Core/command/CommandBus.cs](file://GFramework.Core/command/CommandBus.cs#L1-L62)
- [GFramework.Core/query/QueryBus.cs](file://GFramework.Core/query/QueryBus.cs#L1-L23)
- [GFramework.Core/coroutine/CoroutineScheduler.cs](file://GFramework.Core/coroutine/CoroutineScheduler.cs#L1-L392)
- [GFramework.Core/logging/ConsoleLogger.cs](file://GFramework.Core/logging/ConsoleLogger.cs#L1-L81)

## 架构概览
GFramework 采用 Clean Architecture 分层，强调关注点分离与依赖倒置：

```mermaid
graph TB
UI["UI 层<br/>视图/控制器"] --> Control["控制层<br/>控制器"]
Control --> Sys["逻辑层<br/>系统"]
Sys --> Model["数据层<br/>模型"]
Sys --> Util["工具层<br/>工具"]
Control --> Cmd["命令/查询/事件<br/>横切关注点"]
subgraph "横切关注点"
Cmd["命令"]
Query["查询"]
Event["事件"]
end
```

**图表来源**
- [GFramework.Core/README.md](file://GFramework.Core/README.md#L42-L64)

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

## 详细组件分析

### 架构生命周期与模块化
架构类负责组件注册、初始化阶段推进与销毁流程，支持模块安装与阶段感知。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Arch as "架构"
participant Ctx as "架构上下文"
participant Mod as "模块"
participant Svc as "服务"
Dev->>Arch : InstallModule(模块)
Arch->>Mod : RegisterLifecycleHook(模块)
Arch->>Arch : Container.RegisterPlurality(模块)
Arch->>Mod : Install(架构)
Arch->>Svc : Services.SetContext(上下文)
Arch->>Ctx : Context = ArchitectureContext
Dev->>Arch : Initialize()/InitializeAsync()
Arch->>Arch : Init() 用户自定义初始化
Arch->>Arch : InitializeAllComponentsAsync()
Arch->>Arch : EnterPhase(Ready)
Arch->>Svc : EventBus.Send(Ready事件)
```

**图表来源**
- [GFramework.Core/architecture/Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L38-L566)

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

### 依赖注入容器
IocContainer 提供注册、解析、冻结与线程安全的实例管理，支持单例与多重注册。

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

**图表来源**
- [GFramework.Core/ioc/IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L12-L373)

**章节来源**
- [GFramework.Core/ioc/IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L9-L373)

### 事件系统
EventBus 提供基于类型的事件发布/订阅，支持注册/注销与统一注销列表。

```mermaid
sequenceDiagram
participant Comp as "组件"
participant Bus as "EventBus"
participant Reg as "注册表"
participant Sub as "订阅者"
Comp->>Bus : Send(事件实例)
Bus->>Reg : GetOrAddEvent(Event<T>)
Reg-->>Bus : Event<T>
Bus->>Reg : Trigger(事件实例)
Reg->>Sub : 回调(事件实例)
Comp->>Bus : Register(回调)
Bus->>Reg : GetOrAddEvent(Event<T>)
Reg-->>Bus : IUnRegister
Bus-->>Comp : IUnRegister
Comp->>Bus : UnRegister(回调)
Bus->>Reg : GetEvent(Event<T>)
Reg-->>Bus : UnRegister(回调)
```

**图表来源**
- [GFramework.Core/events/EventBus.cs](file://GFramework.Core/events/EventBus.cs#L1-L55)

**章节来源**
- [GFramework.Core/events/EventBus.cs](file://GFramework.Core/events/EventBus.cs#L1-L55)

### 命令与查询总线
命令/查询总线封装写操作与读操作，支持同步与异步执行。

```mermaid
sequenceDiagram
participant Ctrl as "控制器"
participant CmdBus as "CommandBus"
participant Cmd as "命令"
participant QBus as "QueryBus"
participant Q as "查询"
Ctrl->>CmdBus : Send(命令)
CmdBus->>Cmd : Execute()
Ctrl->>QBus : Send(查询)
QBus->>Q : Do()
Q-->>Ctrl : 结果
```

**图表来源**
- [GFramework.Core/command/CommandBus.cs](file://GFramework.Core/command/CommandBus.cs#L1-L62)
- [GFramework.Core/query/QueryBus.cs](file://GFramework.Core/query/QueryBus.cs#L1-L23)

**章节来源**
- [GFramework.Core/command/CommandBus.cs](file://GFramework.Core/command/CommandBus.cs#L1-L62)
- [GFramework.Core/query/QueryBus.cs](file://GFramework.Core/query/QueryBus.cs#L1-L23)

### 协程调度器
协程调度器基于时间源管理协程执行，支持等待、暂停/恢复、终止与标签管理。

```mermaid
flowchart TD
Start(["Update 调用"]) --> Tick["更新时间源"]
Tick --> Loop["遍历所有协程槽位"]
Loop --> CheckState{"槽位状态?"}
CheckState --> |非运行| NextSlot["下一槽位"]
CheckState --> |运行| HandleWait["处理等待指令"]
HandleWait --> WaitDone{"等待完成?"}
WaitDone --> |否| NextSlot
WaitDone --> |是| MoveNext["推进协程.MoveNext()"]
MoveNext --> Done{"枚举器完成?"}
Done --> |是| Complete["Complete(槽位)"]
Done --> |否| SetWait["设置等待指令"]
SetWait --> NextSlot
Complete --> WakeWaiters["唤醒等待者"]
WakeWaiters --> NextSlot
NextSlot --> End(["结束"])
```

**图表来源**
- [GFramework.Core/coroutine/CoroutineScheduler.cs](file://GFramework.Core/coroutine/CoroutineScheduler.cs#L82-L121)

**章节来源**
- [GFramework.Core/coroutine/CoroutineScheduler.cs](file://GFramework.Core/coroutine/CoroutineScheduler.cs#L1-L392)

### 日志系统
ConsoleLogger 提供控制台日志输出，支持级别与彩色输出。

```mermaid
classDiagram
class ConsoleLogger {
-bool _useColors
-TextWriter _writer
+Write(LogLevel, string, Exception?)
-WriteColored(LogLevel, string)
-GetColor(LogLevel) ConsoleColor
}
class AbstractLogger {
<<abstract>>
+Name() string
+IsEnabledForLevel(LogLevel) bool
+Trace(...)
+Debug(...)
+Info(...)
+Warn(...)
+Error(...)
+Fatal(...)
}
ConsoleLogger --|> AbstractLogger
```

**图表来源**
- [GFramework.Core/logging/ConsoleLogger.cs](file://GFramework.Core/logging/ConsoleLogger.cs#L10-L81)

**章节来源**
- [GFramework.Core/logging/ConsoleLogger.cs](file://GFramework.Core/logging/ConsoleLogger.cs#L1-L81)

### 存储系统
FileStorage 基于文件系统实现存储，支持按 key 细粒度锁保证线程安全。

```mermaid
flowchart TD
ReadStart(["Read/Write 调用"]) --> ToPath["ToPath(key)"]
ToPath --> GetLock["_keyLocks.GetOrAdd(path, _)"]
GetLock --> Acquire["lock(keyLock)"]
Acquire --> Op{"操作类型?"}
Op --> |Read| ReadFile["读取文件内容"]
Op --> |Write| WriteFile["写入文件内容"]
ReadFile --> Deserialize["_serializer.Deserialize<T>(content)"]
WriteFile --> Serialize["_serializer.Serialize(value)"]
Deserialize --> Release["释放锁"]
Serialize --> Release
Release --> ReadEnd(["返回结果"])
```

**图表来源**
- [GFramework.Game/storage/FileStorage.cs](file://GFramework.Game/storage/FileStorage.cs#L144-L255)

**章节来源**
- [GFramework.Game/storage/FileStorage.cs](file://GFramework.Game/storage/FileStorage.cs#L1-L258)

### Godot 时间源
GodotTimeSource 提供基于 Godot 引擎的时间信息，用于协程调度器。

```mermaid
classDiagram
class GodotTimeSource {
-Func~double~ _getDeltaFunc
-double _currentTime
-double _deltaTime
+CurrentTime double
+DeltaTime double
+Update() void
+Reset() void
}
class ITimeSource {
<<interface>>
+CurrentTime double
+DeltaTime double
+Update() void
+Reset() void
}
GodotTimeSource ..|> ITimeSource
```

**图表来源**
- [GFramework.Godot/coroutine/GodotTimeSource.cs](file://GFramework.Godot/coroutine/GodotTimeSource.cs#L9-L44)

**章节来源**
- [GFramework.Godot/coroutine/GodotTimeSource.cs](file://GFramework.Godot/coroutine/GodotTimeSource.cs#L1-L44)

## 依赖分析
GFramework 的依赖关系遵循依赖倒置原则，核心模块不依赖具体实现，通过抽象契约与 IoC 容器管理依赖。

```mermaid
graph LR
Core["GFramework.Core"] --> CoreAbst["GFramework.Core.Abstractions"]
Game["GFramework.Game"] --> GameAbst["GFramework.Game.Abstractions"]
Godot["GFramework.Godot"] --> Core
Godot --> CoreAbst
SrcGen["GFramework.SourceGenerators"] --> CoreAbst
SrcGenAbst["GFramework.SourceGenerators.Abstractions"] --> CoreAbst
SrcGenCommon["GFramework.SourceGenerators.Common"] --> CoreAbst
```

**图表来源**
- [README.md](file://README.md#L33-L51)

**章节来源**
- [README.md](file://README.md#L33-L51)

## 性能考虑
- 协程调度优化
  - 使用标签管理批量终止协程，减少遍历成本。
  - 预热机制一次性推进协程第一步，降低首次启动开销。
  - 等待指令链式更新，避免不必要的 MoveNext 调用。
- 事件系统优化
  - 使用类型事件系统，避免反射与动态派发。
  - 统一注销列表减少内存占用与泄漏风险。
- 依赖注入优化
  - 容器冻结后禁止注册，提升解析性能与安全性。
  - 多重注册支持接口与具体类型，减少解析开销。
- 存储系统优化
  - 按 key 细粒度锁，避免全局锁竞争。
  - 路径清理与防路径逃逸，减少异常开销。
- 日志系统优化
  - 控制台彩色输出仅在标准输出时启用，避免不必要的颜色处理。
  - 级别检查减少日志格式化成本。

**章节来源**
- [GFramework.Core/coroutine/CoroutineScheduler.cs](file://GFramework.Core/coroutine/CoroutineScheduler.cs#L35-L121)
- [GFramework.Core/events/EventBus.cs](file://GFramework.Core/events/EventBus.cs#L1-L55)
- [GFramework.Core/ioc/IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L357-L370)
- [GFramework.Game/storage/FileStorage.cs](file://GFramework.Game/storage/FileStorage.cs#L14-L33)
- [GFramework.Core/logging/ConsoleLogger.cs](file://GFramework.Core/logging/ConsoleLogger.cs#L14-L38)

## 故障排除指南
- 架构初始化失败
  - 检查阶段转换合法性与严格阶段验证配置。
  - 查看日志输出定位失败原因并发送失败事件。
- 组件注册时机错误
  - Ready 阶段后禁止注册组件，除非允许延迟注册。
  - 使用生命周期钩子在合适阶段注册。
- 协程异常处理
  - 协程执行异常会自动完成并清理，避免悬挂。
  - 使用标签批量终止异常协程。
- 事件泄漏排查
  - 使用统一注销列表管理事件注册。
  - 确保节点退出时自动注销事件。
- 存储异常
  - 文件路径非法或路径逃逸会抛出异常。
  - 读取不存在键时抛出文件未找到异常。

**章节来源**
- [GFramework.Core/architecture/Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L164-L183)
- [GFramework.Core/architecture/Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L216-L223)
- [GFramework.Core/coroutine/CoroutineScheduler.cs](file://GFramework.Core/coroutine/CoroutineScheduler.cs#L341-L345)
- [GFramework.Game/storage/FileStorage.cs](file://GFramework.Game/storage/FileStorage.cs#L74-L90)
- [GFramework.Game/storage/FileStorage.cs](file://GFramework.Game/storage/FileStorage.cs#L151-L152)

## 结论
GFramework 通过 Clean Architecture 与模块化设计，为游戏开发提供了清晰、可维护、可扩展的基础设施。遵循本文档的分层原则、依赖注入最佳实践、模块化策略与性能优化建议，能够显著提升团队开发效率与代码质量。建议在团队内推广源码生成器与统一日志规范，持续进行代码审查与性能回归测试。

## 附录

### 代码组织与命名规范
- 文件结构建议
  - 按功能域分层：Models、Systems、Controllers、Utilities。
  - 模块化：每个功能模块独立目录，包含接口与实现。
- 命名约定
  - 接口以 I 前缀，如 ISystem、IModel。
  - 抽象类以 Abstract 前缀，如 AbstractSystem、AbstractModel。
  - 控制器以 Controller 结尾，如 PlayerController。
- 注释标准
  - 公共 API 使用 XML 注释，包含参数、返回值与异常说明。
  - 复杂逻辑添加行内注释，解释设计决策与边界条件。

**章节来源**
- [docs/best-practices/architecture-patterns.md](file://docs/best-practices/architecture-patterns.md#L1-L15)

### 错误处理与调试
- 异常处理
  - 架构初始化失败时进入失败阶段并发送失败事件。
  - 组件销毁时捕获异常并继续销毁其他组件。
- 日志记录
  - 使用日志工厂提供程序配置日志级别与输出格式。
  - 控制台日志支持彩色输出与异常堆栈。
- 性能分析
  - 协程调度器提供活跃协程数量与时间差值。
  - 存储系统支持异步读写，注意锁范围与 IO 操作。

**章节来源**
- [GFramework.Core/architecture/Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L513-L524)
- [GFramework.Core/logging/ConsoleLogger.cs](file://GFramework.Core/logging/ConsoleLogger.cs#L25-L38)
- [GFramework.Core/coroutine/CoroutineScheduler.cs](file://GFramework.Core/coroutine/CoroutineScheduler.cs#L28-L33)

### 团队协作与代码审查
- 代码审查清单
  - 是否遵循分层职责与接口隔离。
  - 是否使用依赖注入与统一生命周期管理。
  - 是否使用事件系统实现松耦合。
  - 是否进行性能与内存优化。
- 团队流程建议
  - 使用源码生成器减少样板代码。
  - 建立模块化开发与集成流水线。
  - 定期进行架构评审与性能回归测试。

**章节来源**
- [docs/best-practices/architecture-patterns.md](file://docs/best-practices/architecture-patterns.md#L1-L15)