# 高级模式教程

<cite>
**本文档引用的文件**
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs)
- [CommandBus.cs](file://GFramework.Core/command/CommandBus.cs)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs)
- [QueryBus.cs](file://GFramework.Core/query/QueryBus.cs)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs)
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs)
- [EasyEvent.cs](file://GFramework.Core/events/EasyEvent.cs)
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs)
- [StateMachineSystem.cs](file://GFramework.Core/state/StateMachineSystem.cs)
- [GameStateMachineSystem.cs](file://GFramework.Game/state/GameStateMachineSystem.cs)
- [CommandBusTests.cs](file://GFramework.Core.Tests/command/CommandBusTests.cs)
- [StateMachineTests.cs](file://GFramework.Core.Tests/state/StateMachineTests.cs)
- [EventBusTests.cs](file://GFramework.Core.Tests/events/EventBusTests.cs)
- [advanced-patterns.md](file://docs/tutorials/advanced-patterns.md)
</cite>

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

## 简介
本教程面向希望深入掌握 GFramework 高级架构模式的开发者，围绕以下主题展开：
- CQRS（命令查询职责分离）：命令总线与查询总线的实现、异步处理、输入输出模型设计
- 事件驱动架构：事件系统高级用法、事件聚合与事件溯源模式
- 插件系统：模块化架构、动态模块加载与模块间通信
- 状态机模式：复杂状态转换、状态持久化与扩展性设计
- 实战示例与最佳实践：通过测试用例与教程文档中的示例路径，帮助读者快速落地

## 项目结构
GFramework 采用分层与模块化的组织方式：
- GFramework.Core：核心框架，包含架构基类、命令/查询总线、事件系统、状态机、生命周期管理等
- GFramework.Game：游戏层实现，包含游戏状态机系统、设置系统、UI 路由等
- GFramework.Godot：Godot 平台适配层，提供平台特定的扩展与集成
- 文档与测试：教程文档与全面的单元测试覆盖关键组件的行为

```mermaid
graph TB
subgraph "核心框架"
CoreArch["架构基类<br/>Architecture.cs"]
CmdBus["命令总线<br/>CommandBus.cs"]
QryBus["查询总线<br/>QueryBus.cs"]
EventBus["事件总线<br/>EventBus.cs"]
StateMachine["状态机<br/>StateMachine.cs"]
StateSys["状态机系统<br/>StateMachineSystem.cs"]
end
subgraph "游戏层"
GameMod["模块基类<br/>AbstractModule.cs"]
GameSM["游戏状态机系统<br/>GameStateMachineSystem.cs"]
end
subgraph "文档与测试"
Docs["高级模式教程<br/>advanced-patterns.md"]
CmdTests["命令总线测试<br/>CommandBusTests.cs"]
StateTests["状态机测试<br/>StateMachineTests.cs"]
EventTests["事件总线测试<br/>EventBusTests.cs"]
end
CoreArch --> CmdBus
CoreArch --> QryBus
CoreArch --> EventBus
CoreArch --> StateMachine
StateMachine --> StateSys
GameMod --> CoreArch
GameSM --> StateSys
Docs --> CmdBus
Docs --> QryBus
Docs --> EventBus
Docs --> StateMachine
CmdTests --> CmdBus
StateTests --> StateMachine
EventTests --> EventBus
```

**图表来源**
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [CommandBus.cs](file://GFramework.Core/command/CommandBus.cs#L1-L62)
- [QueryBus.cs](file://GFramework.Core/query/QueryBus.cs#L1-L23)
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs#L1-L55)
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs#L1-L276)
- [StateMachineSystem.cs](file://GFramework.Core/state/StateMachineSystem.cs#L1-L96)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L1-L33)
- [GameStateMachineSystem.cs](file://GFramework.Game/state/GameStateMachineSystem.cs#L1-L26)
- [advanced-patterns.md](file://docs/tutorials/advanced-patterns.md#L1-L800)
- [CommandBusTests.cs](file://GFramework.Core.Tests/command/CommandBusTests.cs#L1-L265)
- [StateMachineTests.cs](file://GFramework.Core.Tests/state/StateMachineTests.cs#L1-L444)
- [EventBusTests.cs](file://GFramework.Core.Tests/events/EventBusTests.cs#L1-L85)

**章节来源**
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L1-L33)
- [advanced-patterns.md](file://docs/tutorials/advanced-patterns.md#L1-L800)

## 核心组件
本节聚焦于 CQRS、事件驱动与状态机三大核心能力，以及它们在架构中的位置与协作方式。

- 命令查询职责分离（CQRS）
  - 命令总线：同步与异步执行命令，支持带返回值与无返回值两种模式
  - 查询总线：执行查询并返回结果
  - 输入输出模型：命令/查询分别通过输入接口约束参数，确保职责清晰

- 事件驱动架构
  - 事件总线：基于类型的事件发送、注册与注销
  - 简易事件：最小化实现，便于快速注册/触发
  - 事件溯源：教程文档提供了事件存储、快照与聚合根重建的思路

- 状态机模式
  - 状态机：注册/注销状态、状态切换、历史记录与回退
  - 状态机系统：上下文感知、生命周期钩子、状态变更事件通知
  - 游戏状态机系统：针对游戏场景的状态判断与获取

**章节来源**
- [CommandBus.cs](file://GFramework.Core/command/CommandBus.cs#L1-L62)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L1-L53)
- [QueryBus.cs](file://GFramework.Core/query/QueryBus.cs#L1-L23)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L1-L29)
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs#L1-L55)
- [EasyEvent.cs](file://GFramework.Core/events/EasyEvent.cs#L1-L39)
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs#L1-L276)
- [StateMachineSystem.cs](file://GFramework.Core/state/StateMachineSystem.cs#L1-L96)
- [GameStateMachineSystem.cs](file://GFramework.Game/state/GameStateMachineSystem.cs#L1-L26)

## 架构概览
GFramework 的架构基类负责模块安装、生命周期管理、阶段转换与组件注册。它通过 IOC 容器统一管理系统、模型与工具，并在初始化完成后冻结容器，确保运行时的稳定性。

```mermaid
classDiagram
class Architecture {
+InstallModule(module)
+RegisterSystem(system)
+RegisterModel(model)
+RegisterUtility(utility)
+Initialize()
+InitializeAsync()
+Destroy()
-EnterPhase(next)
-ValidatePhaseTransition(next)
-NotifyPhase(phase)
-NotifyPhaseAwareObjects(phase)
-RegisterLifecycleComponent(component)
}
class IArchitectureModule {
+Install(architecture)
+OnArchitecturePhase(phase)
+OnPhase(phase, architecture)
}
class AbstractModule {
+Install(architecture)
+OnArchitecturePhase(phase)
+OnPhase(phase, architecture)
}
Architecture --> IArchitectureModule : "安装模块"
AbstractModule ..|> IArchitectureModule
```

**图表来源**
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L38-L48)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L423-L460)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L511-L566)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L9-L33)

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

## 详细组件分析

### CQRS 模式实现与应用
CQRS 将写操作（命令）与读操作（查询）分离，提升系统的可扩展性与可维护性。GFramework 提供了命令总线与查询总线，配合抽象命令/查询基类，形成清晰的输入输出模型。

- 命令总线
  - 支持同步与异步命令执行
  - 带返回值与无返回值两种 Send/SendAsync 重载
  - 参数校验：空命令抛出异常

- 查询总线
  - 执行查询并返回结果
  - 通过抽象查询基类约束输入与输出

- 输入输出模型
  - 命令/查询均通过输入接口约束参数，确保职责单一
  - 可结合上下文与日志生成器，实现跨组件的上下文感知

```mermaid
sequenceDiagram
participant Client as "客户端"
participant CmdBus as "命令总线"
participant Cmd as "命令"
participant QryBus as "查询总线"
participant Qry as "查询"
Client->>CmdBus : "Send/ICommand"
CmdBus->>Cmd : "Execute()"
Cmd-->>Client : "完成/返回值"
Client->>CmdBus : "SendAsync/IAsyncCommand"
CmdBus->>Cmd : "ExecuteAsync()"
Cmd-->>Client : "Task/Task<TResult>"
Client->>QryBus : "Send/IQuery<TResult>"
QryBus->>Qry : "Do()"
Qry-->>Client : "TResult"
```

**图表来源**
- [CommandBus.cs](file://GFramework.Core/command/CommandBus.cs#L16-L61)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L11-L27)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L35-L53)
- [QueryBus.cs](file://GFramework.Core/query/QueryBus.cs#L16-L22)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L11-L29)

- 实战示例与最佳实践
  - 教程文档提供了完整的 CQRS 示例：命令（创建玩家）、查询（获取玩家、统计信息）与领域事件
  - 使用上下文发送命令/查询，结合日志记录错误与成功信息
  - 建议将命令/查询输入参数封装为独立 DTO，便于测试与演进

**章节来源**
- [CommandBus.cs](file://GFramework.Core/command/CommandBus.cs#L1-L62)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L1-L53)
- [QueryBus.cs](file://GFramework.Core/query/QueryBus.cs#L1-L23)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L1-L29)
- [CommandBusTests.cs](file://GFramework.Core.Tests/command/CommandBusTests.cs#L1-L265)
- [advanced-patterns.md](file://docs/tutorials/advanced-patterns.md#L159-L205)

### 事件驱动架构实现
GFramework 的事件系统提供基于类型的事件发送、注册与注销，支持同步与异步处理。教程文档进一步展示了事件溯源与聚合根重建的思路。

- 事件总线
  - Send<T>() 自动实例化事件并触发
  - Send<T>(T e) 直接触发事件实例
  - Register/UnRegister 提供监听与注销

- 简易事件
  - 最小化实现，适合轻量事件场景

- 事件溯源与聚合根重建
  - 事件存储：按流存储事件，定期创建快照
  - 聚合根重建：从历史事件重建状态，清理未提交事件

```mermaid
flowchart TD
Start(["事件发布"]) --> Persist["持久化事件(可选)"]
Persist --> SyncHandlers["同步处理器列表"]
Persist --> AsyncHandlers["异步处理器列表"]
SyncHandlers --> HandleSync["逐个处理同步处理器"]
AsyncHandlers --> CollectTasks["收集异步任务"]
CollectTasks --> AwaitTasks["等待所有异步处理器完成"]
HandleSync --> End(["完成"])
AwaitTasks --> End
```

**图表来源**
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs#L16-L54)
- [EasyEvent.cs](file://GFramework.Core/events/EasyEvent.cs#L8-L39)
- [advanced-patterns.md](file://docs/tutorials/advanced-patterns.md#L519-L690)

**章节来源**
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs#L1-L55)
- [EasyEvent.cs](file://GFramework.Core/events/EasyEvent.cs#L1-L39)
- [EventBusTests.cs](file://GFramework.Core.Tests/events/EventBusTests.cs#L1-L85)
- [advanced-patterns.md](file://docs/tutorials/advanced-patterns.md#L515-L690)

### 插件系统开发（模块化架构）
GFramework 通过架构基类与模块基类实现模块化与动态加载。模块安装时注册生命周期钩子，参与架构阶段转换与组件初始化。

- 模块安装
  - InstallModule：安装模块、注册生命周期钩子、调用模块 Install
  - 模块生命周期：OnArchitecturePhase、OnPhase

- 架构阶段管理
  - EnterPhase：验证阶段转换、通知阶段变更、通知阶段感知对象
  - 初始化顺序：工具 → 模型 → 系统，按阶段推进

```mermaid
sequenceDiagram
participant Arch as "架构"
participant Mod as "模块"
participant Hook as "生命周期钩子"
Arch->>Mod : "Install(architecture)"
Arch->>Hook : "RegisterLifecycleHook(hook)"
Hook-->>Arch : "OnPhase(phase, architecture)"
Arch->>Mod : "OnArchitecturePhase(phase)"
```

**图表来源**
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L38-L48)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L216-L223)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L189-L196)
- [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs#L16-L32)

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

### 状态机模式高级应用
GFramework 的状态机支持注册/注销状态、状态切换、历史记录与回退。状态机系统在状态切换时发送状态变更事件，便于监听与响应。

- 状态机核心能力
  - Register/Unregister：注册与注销状态
  - ChangeTo/CanChangeTo：切换与校验状态
  - 历史记录：最大历史长度限制，GoBack 回退
  - 回调：OnStateChanging/OnStateChanged/OnTransitionRejected

- 状态机系统
  - 上下文感知：为状态设置架构上下文
  - 生命周期：Init/Destroy
  - 事件通知：状态切换时发送状态变更事件

- 游戏状态机系统
  - IsIn<T>()：检查当前状态类型
  - Get<T>()：获取当前状态实例

```mermaid
classDiagram
class StateMachine {
+Register(state)
+Unregister<T>()
+ChangeTo<T>()
+CanChangeTo<T>()
+GoBack()
+GetStateHistory()
+GetPreviousState()
+ClearHistory()
#ChangeInternal(next)
#ChangeInternalWithoutHistory(next)
#OnStateChanging(from,to)
#OnStateChanged(from,to)
#OnTransitionRejected(from,to)
}
class StateMachineSystem {
+SetContext(context)
+GetContext()
+Init()
+Destroy()
#ChangeInternal(next)
}
class GameStateMachineSystem {
+IsIn<T>()
+Get<T>()
}
StateMachineSystem --|> StateMachine
GameStateMachineSystem --|> StateMachineSystem
```

**图表来源**
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs#L27-L276)
- [StateMachineSystem.cs](file://GFramework.Core/state/StateMachineSystem.cs#L14-L96)
- [GameStateMachineSystem.cs](file://GFramework.Game/state/GameStateMachineSystem.cs#L9-L26)

**章节来源**
- [StateMachine.cs](file://GFramework.Core/state/StateMachine.cs#L1-L276)
- [StateMachineSystem.cs](file://GFramework.Core/state/StateMachineSystem.cs#L1-L96)
- [GameStateMachineSystem.cs](file://GFramework.Game/state/GameStateMachineSystem.cs#L1-L26)
- [StateMachineTests.cs](file://GFramework.Core.Tests/state/StateMachineTests.cs#L1-L444)

## 依赖关系分析
GFramework 的核心组件之间存在清晰的依赖关系与协作模式：

- 架构基类依赖 IOC 容器与事件总线，统一管理模块、系统、模型与工具
- 命令/查询总线依赖抽象命令/查询基类，确保输入输出模型一致
- 事件总线与状态机系统通过事件进行解耦协作
- 游戏状态机系统继承状态机系统，扩展游戏场景的状态判断

```mermaid
graph TB
Arch["架构基类"] --> IOC["IOC 容器"]
Arch --> EB["事件总线"]
Arch --> Sys["系统注册"]
Arch --> Model["模型注册"]
Arch --> Util["工具注册"]
CmdBus["命令总线"] --> AbsCmd["抽象命令"]
QryBus["查询总线"] --> AbsQry["抽象查询"]
StateSys["状态机系统"] --> StateMachine["状态机"]
GameSM["游戏状态机系统"] --> StateSys
EB --> EasyEvt["简易事件"]
```

**图表来源**
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L72-L77)
- [CommandBus.cs](file://GFramework.Core/command/CommandBus.cs#L9-L62)
- [AbstractCommand.cs](file://GFramework.Core/command/AbstractCommand.cs#L11-L53)
- [QueryBus.cs](file://GFramework.Core/query/QueryBus.cs#L8-L23)
- [AbstractQuery.cs](file://GFramework.Core/query/AbstractQuery.cs#L11-L29)
- [StateMachineSystem.cs](file://GFramework.Core/state/StateMachineSystem.cs#L14-L96)
- [GameStateMachineSystem.cs](file://GFramework.Game/state/GameStateMachineSystem.cs#L9-L26)
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs#L8-L55)
- [EasyEvent.cs](file://GFramework.Core/events/EasyEvent.cs#L8-L39)

**章节来源**
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [CommandBus.cs](file://GFramework.Core/command/CommandBus.cs#L1-L62)
- [QueryBus.cs](file://GFramework.Core/query/QueryBus.cs#L1-L23)
- [EventBus.cs](file://GFramework.Core/events/EventBus.cs#L1-L55)
- [StateMachineSystem.cs](file://GFramework.Core/state/StateMachineSystem.cs#L1-L96)
- [GameStateMachineSystem.cs](file://GFramework.Game/state/GameStateMachineSystem.cs#L1-L26)

## 性能考虑
- 命令/查询总线
  - 同步命令建议在主线程执行，避免频繁切换线程上下文
  - 异步命令优先使用 SendAsync，充分利用异步 I/O 与协程调度
  - 输入输出模型尽量简单，减少序列化/反序列化成本

- 事件系统
  - 事件处理器应避免长时间阻塞，必要时拆分为异步处理器
  - 事件存储需考虑并发写入与快照策略，降低重放成本

- 状态机
  - 历史记录大小受控，避免内存膨胀
  - 状态切换回调应尽量轻量，避免在 OnStateChanging/OnStateChanged 中执行耗时操作

[本节为通用指导，无需列出章节来源]

## 故障排除指南
- 命令总线
  - 空命令异常：确保传入的命令不为 null
  - 异步命令执行失败：检查异常捕获与日志记录，定位具体命令实现

- 查询总线
  - 查询执行异常：检查查询输入参数与业务逻辑，确保 Do() 正确实现

- 事件总线
  - 处理器未触发：确认事件类型匹配与处理器注册顺序
  - 注销无效：确保注销的是同一委托实例

- 状态机
  - 无法切换状态：检查 CanTransitionTo 与状态注册情况
  - 回退失败：确认历史记录中仍存在有效状态

**章节来源**
- [CommandBusTests.cs](file://GFramework.Core.Tests/command/CommandBusTests.cs#L48-L123)
- [EventBusTests.cs](file://GFramework.Core.Tests/events/EventBusTests.cs#L28-L77)
- [StateMachineTests.cs](file://GFramework.Core.Tests/state/StateMachineTests.cs#L132-L195)

## 结论
通过 CQRS、事件驱动与状态机三大模式，GFramework 为复杂游戏系统提供了清晰的架构骨架。结合模块化与上下文感知能力，开发者可以在保证可维护性的同时，实现高性能与高扩展性的系统设计。建议在实际项目中：
- 明确命令/查询边界，使用输入输出模型约束参数
- 采用事件总线解耦模块，必要时引入事件溯源增强可观测性
- 善用状态机管理复杂状态流转，结合游戏状态机系统进行场景化扩展

[本节为总结性内容，无需列出章节来源]

## 附录
- 教程文档中的完整 CQRS 示例与 DDD 设计思路，可作为实战参考
- 单元测试覆盖命令总线、状态机与事件总线的关键行为，便于对照与扩展

**章节来源**
- [advanced-patterns.md](file://docs/tutorials/advanced-patterns.md#L1-L800)
- [CommandBusTests.cs](file://GFramework.Core.Tests/command/CommandBusTests.cs#L1-L265)
- [StateMachineTests.cs](file://GFramework.Core.Tests/state/StateMachineTests.cs#L1-L444)
- [EventBusTests.cs](file://GFramework.Core.Tests/events/EventBusTests.cs#L1-L85)