mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-26 06:16:43 +08:00
a79f02c987
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件 - 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明 - 提供完整的 API 使用示例路径、最佳实践与性能建议 - 包含架构图、依赖关系图与故障排查指南 - 添加测试用例参考与扩展方法说明 - [skip ci]
18 KiB
18 KiB
架构分层
**本文引用的文件** - [架构基类 Architecture.cs](file://GFramework.Core/architecture/Architecture.cs) - [架构接口 IArchitecture.cs](file://GFramework.Core.Abstractions/architecture/IArchitecture.cs) - [架构上下文 ArchitectureContext.cs](file://GFramework.Core/architecture/ArchitectureContext.cs) - [游戏上下文 GameContext.cs](file://GFramework.Core/architecture/GameContext.cs) - [上下文感知基类 ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs) - [架构常量 ArchitectureConstants.cs](file://GFramework.Core/architecture/ArchitectureConstants.cs) - [架构配置 ArchitectureConfiguration.cs](file://GFramework.Core/architecture/ArchitectureConfiguration.cs) - [抽象模型 AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs) - [抽象系统 AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs) - [抽象模块 AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs) - [控制器接口 IController.cs](file://GFramework.Core.Abstractions/controller/IController.cs) - [架构模式最佳实践 architecture-patterns.md](file://docs/best-practices/architecture-patterns.md) - [Godot 入门教程 getting-started.md](file://docs/tutorials/getting-started.md)目录
简介
本文件面向 GFramework 的架构分层最佳实践，系统阐述数据层(AbstractModel)、业务逻辑层(AbstractSystem)、控制层(Node/IController)与表现层的职责划分与协作方式，结合仓库中的核心实现与官方最佳实践文档，给出清晰的分层设计、数据流与交互模式，并提供正反面案例对比、测试策略与维护建议。
项目结构
GFramework 采用“核心层(Core) + 平台适配层(Godot) + 游戏层(Game) + 文档(docs)”的分层组织方式：
- Core 层提供跨平台的架构内核、生命周期、事件、命令/查询总线、上下文与 IoC 容器等基础设施
- Godot 层提供与 Godot 平台相关的扩展、节点工具、时间源、UI 注册表等
- Game 层提供游戏域的模块化能力（如设置、状态机、UI 路由管线等）
- 文档层提供最佳实践与教程，指导如何正确分层与组织代码
graph TB
subgraph "核心层(Core)"
A["架构基类<br/>Architecture.cs"]
B["架构接口<br/>IArchitecture.cs"]
C["架构上下文<br/>ArchitectureContext.cs"]
D["游戏上下文<br/>GameContext.cs"]
E["上下文感知基类<br/>ContextAwareBase.cs"]
F["抽象模型<br/>AbstractModel.cs"]
G["抽象系统<br/>AbstractSystem.cs"]
end
subgraph "平台层(Godot)"
H["Godot 扩展与工具"]
end
subgraph "游戏层(Game)"
I["抽象模块<br/>AbstractModule.cs"]
end
subgraph "文档(docs)"
J["架构模式最佳实践<br/>architecture-patterns.md"]
K["入门教程<br/>getting-started.md"]
end
A --> C
C --> F
C --> G
E --> F
E --> G
I --> A
J --> A
K --> A
图表来源
- 架构基类 Architecture.cs
- 架构接口 IArchitecture.cs
- 架构上下文 ArchitectureContext.cs
- 游戏上下文 GameContext.cs
- 上下文感知基类 ContextAwareBase.cs
- 抽象模型 AbstractModel.cs
- 抽象系统 AbstractSystem.cs
- 抽象模块 AbstractModule.cs
- 架构模式最佳实践 architecture-patterns.md
- Godot 入门教程 getting-started.md
章节来源
核心组件
- 架构基类与生命周期
- Architecture 负责阶段式生命周期管理、组件注册与初始化、销毁流程、事件广播与阶段通知
- ArchitectureConstants 定义阶段顺序与允许的转换
- ArchitectureConfiguration 提供日志与架构选项的默认配置
- 上下文与依赖注入
- ArchitectureContext 提供对系统/模型/工具的获取与命令/查询/事件的执行入口
- GameContext 管理多架构上下文绑定与获取
- ContextAwareBase 为组件提供上下文感知能力
- 分层基类
- AbstractModel：数据层基类，实现 IModel，提供初始化与阶段事件处理
- AbstractSystem：业务逻辑层基类，实现 ISystem，提供初始化/销毁与阶段事件处理
- 模块化
- AbstractModule：模块基类，支持 Install 与阶段回调
章节来源
- 架构基类 Architecture.cs
- 架构常量 ArchitectureConstants.cs
- 架构配置 ArchitectureConfiguration.cs
- 架构上下文 ArchitectureContext.cs
- 游戏上下文 GameContext.cs
- 上下文感知基类 ContextAwareBase.cs
- 抽象模型 AbstractModel.cs
- 抽象系统 AbstractSystem.cs
- 抽象模块 AbstractModule.cs
架构概览
GFramework 的分层架构围绕“数据层-业务逻辑层-控制层-表现层”展开，配合事件总线与上下文上下文，形成清晰的职责边界与数据流：
graph TB
subgraph "表现层"
N["节点/页面控制器<br/>Node/IController"]
end
subgraph "控制层"
C["控制器<br/>IController"]
end
subgraph "业务逻辑层"
S["系统<br/>AbstractSystem"]
end
subgraph "数据层"
M["模型<br/>AbstractModel"]
end
subgraph "基础设施"
X["架构上下文<br/>ArchitectureContext"]
E["事件总线<br/>IEventBus"]
Q["命令/查询总线<br/>ICommandBus/IQueryBus"]
end
N --> C
C --> S
S --> M
N --> E
C --> E
S --> E
N --> Q
C --> Q
S --> Q
X --> N
X --> C
X --> S
X --> M
图表来源
章节来源
详细组件分析
数据层(AbstractModel)
- 职责
- 仅负责状态存储与状态变更事件的触发
- 通过 BindableProperty 等可绑定属性对外暴露状态
- 对外发送领域事件（如死亡事件），不包含业务逻辑
- 生命周期
- 在 BeforeModelInit → AfterModelInit 阶段初始化
- 支持 OnArchitecturePhase 阶段事件处理
- 与上下文的关系
- 通过 ContextAwareBase 获取架构上下文，便于发送事件或访问其他组件
classDiagram
class AbstractModel {
+OnInit()*
+OnArchitecturePhase(phase)
}
class ContextAwareBase {
-Context
+SetContext(context)
+GetContext()
}
AbstractModel --|> ContextAwareBase
图表来源
章节来源
业务逻辑层(AbstractSystem)
- 职责
- 负责业务规则与流程编排
- 订阅事件、读取模型状态、向模型写入状态、向外发送事件
- 生命周期
- 在 BeforeSystemInit → AfterSystemInit 阶段初始化
- 支持 Init/Destroy 与 OnArchitecturePhase
- 与上下文的关系
- 通过 ArchitectureContext 获取模型/系统/工具，发送命令/查询/事件
classDiagram
class AbstractSystem {
+Init()
+Destroy()
+OnInit()*
+OnDestroy()
+OnArchitecturePhase(phase)
}
class ArchitectureContext {
+GetModel<T>()
+GetSystem<T>()
+GetUtility<T>()
+SendEvent(...)
+SendCommand(...)
+SendQuery(...)
}
AbstractSystem --> ArchitectureContext : "获取组件/发送消息"
图表来源
章节来源
控制层(Node/IController)
- 职责
- 连接用户输入与业务逻辑
- 监听模型状态变化并驱动表现层更新
- 通过 Context 发送事件（如输入事件）
- 与上下文的关系
- 通过 Context.GetModel 获取数据层引用
- 通过 Context.SendEvent 触发业务逻辑层处理
sequenceDiagram
participant UI as "表现层节点"
participant Ctrl as "控制器"
participant Ctx as "架构上下文"
participant Sys as "业务逻辑层系统"
participant Model as "数据层模型"
UI->>Ctrl : "_Input(...)" 用户输入
Ctrl->>Ctx : "SendEvent(输入事件)"
Ctx-->>Sys : "事件投递"
Sys->>Model : "读取/写入状态"
Sys-->>UI : "发送状态变化事件"
UI->>Model : "注册状态监听"
Model-->>UI : "状态变更回调"
UI->>UI : "更新表现层"
图表来源
章节来源
表现层
- 职责
- 响应模型状态变化与系统事件，渲染 UI、播放动画、播放音效
- 与上下文的关系
- 通过 Context.GetModel 获取模型引用，注册状态监听
- 通过 Context.SendEvent 发送输入事件
章节来源
模块化与阶段管理
- 模块安装
- 通过 AbstractModule.Install 将系统/工具注册到架构
- 模块可接收阶段回调，参与架构生命周期
- 阶段转换
- ArchitectureConstants 定义线性阶段序列与允许转换
- Architecture.ValidatePhaseTransition 校验转换合法性
flowchart TD
Start(["架构初始化"]) --> BeforeU["BeforeUtilityInit"]
BeforeU --> AfterU["AfterUtilityInit"]
AfterU --> BeforeM["BeforeModelInit"]
BeforeM --> AfterM["AfterModelInit"]
AfterM --> BeforeS["BeforeSystemInit"]
BeforeS --> AfterS["AfterSystemInit"]
AfterS --> Ready["Ready"]
Ready --> Destroying["Destroying"]
Destroying --> Destroyed["Destroyed"]
图表来源
章节来源
依赖分析
- 组件耦合
- AbstractSystem/AbstractModel 通过 ContextAwareBase 间接依赖架构上下文，降低对具体实现的耦合
- 控制器通过 IController 接口与表现层解耦
- 直接依赖
- AbstractSystem 依赖 ArchitectureContext 获取模型/系统/工具
- ArchitectureContext 依赖 IoC 容器与各总线（命令/查询/事件）
- 外部依赖
- 日志工厂、环境、模块等通过配置与服务注入
graph LR
Sys["AbstractSystem"] --> Ctx["ArchitectureContext"]
Model["AbstractModel"] --> Ctx
Ctx --> BusCmd["ICommandBus"]
Ctx --> BusQry["IQueryBus"]
Ctx --> BusEvt["IEventBus"]
Ctx --> IOC["IIocContainer"]
Cfg["ArchitectureConfiguration"] --> Arch["Architecture"]
Const["ArchitectureConstants"] --> Arch
图表来源
- 抽象系统 AbstractSystem.cs
- 抽象模型 AbstractModel.cs
- 架构上下文 ArchitectureContext.cs
- 架构基类 Architecture.cs
- 架构配置 ArchitectureConfiguration.cs
- 架构常量 ArchitectureConstants.cs
章节来源
性能考虑
- 初始化阶段化
- 通过 BeforeUtilityInit/AfterUtilityInit、BeforeModelInit/AfterModelInit、BeforeSystemInit/AfterSystemInit 的分层初始化，减少一次性初始化开销
- 异步初始化
- 支持 IAsyncInitializable 与 InitializeAsync，适合异步 I/O 或长耗时初始化
- 事件与总线
- 使用事件总线解耦组件，避免循环依赖与强耦合
- 上下文缓存
- ArchitectureContext 对服务进行简单缓存，减少重复解析成本
章节来源
故障排查指南
- 阶段转换异常
- 现象：非法阶段转换导致异常
- 排查：检查 ArchitectureConstants 的转换表与配置项 ArchitectureConfiguration.ArchitectureProperties.StrictPhaseValidation
- 组件注册时机
- 现象：在 Ready 阶段后注册组件抛出异常
- 排查：确认注册时机在 InitializeInternalAsync 完成冻结前；必要时开启 ArchitectureConfiguration.ArchitectureProperties.AllowLateRegistration
- 依赖缺失
- 现象：SendQuery/SendCommand/SendEvent 抛出“未注册”异常
- 排查：确认对应总线已在架构中注册；检查模块安装与服务注入
- 销毁异常
- 现象：Destroy 期间某个组件抛错导致整体销毁中断
- 排查：查看 Architecture.cs 中的异常捕获与继续销毁逻辑
章节来源
- 架构基类 Architecture.cs
- 架构基类 Architecture.cs
- 架构基类 Architecture.cs
- 架构上下文 ArchitectureContext.cs
- 架构上下文 ArchitectureContext.cs
- 架构上下文 ArchitectureContext.cs
结论
GFramework 的分层架构通过“数据层-业务逻辑层-控制层-表现层”的职责分离与事件驱动，实现了高内聚、低耦合与可测试性。依托 Architecture 的阶段化生命周期、ArchitectureContext 的统一访问入口与 ContextAwareBase 的上下文感知能力，开发者可以清晰地组织 PlayerModel、PlayerMovementSystem、PlayerController 等组件，构建稳定且易维护的游戏架构。
附录
分层设计示例与对比
- 正确分层示例
- 数据层：PlayerModel 仅持有状态与状态变更事件
- 业务逻辑层：PlayerMovementSystem 读取输入事件、更新模型状态并发送移动事件
- 控制层：Node/IController 接收输入、转发事件、监听模型状态并驱动表现层
- 反面案例
- 控制器同时承担数据层与业务逻辑层职责，导致难以测试与维护
章节来源
测试策略
- 单元测试
- 使用 ArchitectureConfiguration 与 ArchitectureServices 自定义日志与服务，隔离外部依赖
- 通过 ArchitectureContext.GetService 获取受测组件，断言事件与状态变更
- 集成测试
- 使用 Architecture.Initialize/InitializeAsync 完整初始化，验证阶段转换与组件协作
- 模拟与替换
- 使用接口（如 IModel/ISystem/IEventBus/ICommandBus/IQueryBus）与 IoC 注入，替换真实实现
章节来源