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

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

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

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

15 KiB

Raw Blame History

模块化架构

**本文档引用的文件** - [GFramework.Core.csproj](file://GFramework.Core/GFramework.Core.csproj) - [GFramework.Core.Abstractions.csproj](file://GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj) - [GFramework.Game.csproj](file://GFramework.Game/GFramework.Game.csproj) - [GFramework.Game.Abstractions.csproj](file://GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj) - [GFramework.Godot.csproj](file://GFramework.Godot/GFramework.Godot.csproj) - [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj) - [架构.cs](file://GFramework.Core/architecture/Architecture.cs) - [架构配置.cs](file://GFramework.Core/architecture/ArchitectureConfiguration.cs) - [游戏上下文.cs](file://GFramework.Core/architecture/GameContext.cs) - [模块接口.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureModule.cs) - [抽象模块.cs](file://GFramework.Game/architecture/AbstractModule.cs) - [抽象Godot模块.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs) - [IGodot模块.cs](file://GFramework.Godot/architecture/IGodotModule.cs) - [事件总线.cs](file://GFramework.Core/events/EventBus.cs) - [简单事件.cs](file://GFramework.Core/events/EasyEvent.cs) - [设置系统.cs](file://GFramework.Game/setting/SettingsSystem.cs) - [UI路由器基类.cs](file://GFramework.Game/ui/UiRouterBase.cs)

引言

本文件面向GFramework的模块化架构，系统性阐述模块边界设计、安装与卸载流程、模块内系统与工具的组织方式、模块间通过事件的松耦合通信模式，以及模块化架构的测试策略与维护建议。文档旨在帮助开发者在不牺牲可扩展性与可维护性的前提下，快速搭建稳定可靠的模块化系统。

项目结构

GFramework采用多项目分层与模块化组合的方式：

核心层：提供架构基座、生命周期管理、事件系统、IoC容器等通用能力
游戏层：在核心之上提供游戏域的系统与工具（如设置系统、UI路由器）
平台适配层：针对Godot平台提供模块与节点绑定能力
抽象层：定义跨层接口契约，确保模块边界清晰、可替换

graph TB
subgraph "核心层"
Core["GFramework.Core<br/>架构/事件/IoC/系统/模型/工具"]
CoreAbst["GFramework.Core.Abstractions<br/>接口契约"]
end
subgraph "游戏层"
Game["GFramework.Game<br/>设置系统/UI路由器"]
GameAbst["GFramework.Game.Abstractions<br/>游戏域接口"]
end
subgraph "平台层"
Godot["GFramework.Godot<br/>Godot模块/节点/日志/场景注册"]
Gen["GFramework.Godot.SourceGenerators<br/>源生成器"]
end
CoreAbst --> Core
GameAbst --> Game
Core --> Game
Game --> Godot
CoreAbst --> Godot
GameAbst --> Godot
Gen --> Godot

图表来源

章节来源

核心组件

架构基座：统一管理模块安装、组件注册、生命周期与阶段转换
模块接口与抽象：定义模块安装协议与阶段感知能力
事件系统：提供类型化事件总线，支持模块间松耦合通信
游戏域系统：设置系统、UI路由器等具体业务模块

章节来源

架构总览

模块化架构围绕“架构基座 + 模块 + 系统/工具”的层次展开。模块通过Install接入架构，注册自身系统与工具，参与架构生命周期与阶段转换；模块间通过事件总线进行解耦通信。

classDiagram
class 架构基座 {
+InstallModule(module)
+RegisterSystem(system)
+RegisterModel(model)
+RegisterUtility(utility)
+Initialize()/InitializeAsync()
+Destroy()
+EnterPhase(phase)
}
class 模块接口 {
<<interface>>
+Install(架构)
+OnPhase(...)
+OnArchitecturePhase(...)
}
class 抽象模块 {
+Install(架构)
+OnPhase(...)
+OnArchitecturePhase(...)
}
class 事件总线 {
+Send<T>()
+Register<T>(handler)
+UnRegister<T>(handler)
}
class 设置系统 {
+ApplyAll()
+Apply<T>()
+Apply(type)
}
class UI路由器基类 {
+Push(key,...)
+Pop(policy)
+Replace(key,...)
+Clear()
+RegisterHandler(...)
+UnregisterHandler(...)
}
模块接口 <|.. 抽象模块
架构基座 --> 模块接口 : "InstallModule()"
架构基座 --> 事件总线 : "使用"
设置系统 ..|> 系统接口
UI路由器基类 ..|> 系统接口
设置系统 --> 事件总线 : "发送设置事件"
UI路由器基类 --> 事件总线 : "发送UI切换事件"

图表来源

详细组件分析

模块边界与设计原则

边界清晰：模块通过IArchitectureModule定义安装入口与阶段感知，避免跨模块直接耦合
单一职责：每个模块聚焦于特定领域（如设置、UI、音频等），内部聚合相关系统与工具
可替换性：模块依赖接口而非具体实现，便于在不同平台或场景下替换
可观测性：模块安装与阶段变化均通过日志记录，便于问题定位

章节来源

模块安装与卸载流程

安装流程：架构调用InstallModule注册生命周期钩子、将模块注册到IoC容器并执行模块Install
卸载流程：通过架构Destroy触发销毁阶段，按注册逆序调用IDisposable组件的Destroy

sequenceDiagram
participant App as "应用"
participant Arch as "架构基座"
participant Mod as "模块"
participant Ctn as "IoC容器"
participant Bus as "事件总线"
App->>Arch : "InstallModule(模块)"
Arch->>Arch : "RegisterLifecycleHook(模块)"
Arch->>Ctn : "RegisterPlurality(模块)"
Arch->>Mod : "Install(架构)"
Arch->>Bus : "发送就绪事件(可选)"
App->>Arch : "Destroy()"
Arch->>Arch : "EnterPhase(Destroying)"
Arch->>Bus : "发送销毁中事件"
loop 逆序销毁
Arch->>Mod : "Destroy()"
end
Arch->>Arch : "EnterPhase(Destroyed)"
Arch->>Bus : "发送已销毁事件"

图表来源

章节来源

模块内系统与工具组织

系统注册：架构提供RegisterSystem/RegisterModel/RegisterUtility，统一设置上下文、注册生命周期并按阶段初始化
初始化阶段：工具 → 模型 → 系统，阶段间可插入自定义逻辑
上下文绑定：GameContext提供多架构上下文绑定与查询，便于跨模块访问

flowchart TD
Start(["模块Install"]) --> RegSys["注册系统/模型/工具"]
RegSys --> SetCtx["设置上下文"]
SetCtx --> RegLC["注册生命周期组件"]
RegLC --> PhaseTools["进入工具初始化阶段"]
PhaseTools --> InitTools["初始化工具"]
InitTools --> PhaseModels["进入模型初始化阶段"]
PhaseModels --> InitModels["初始化模型"]
InitModels --> PhaseSystems["进入系统初始化阶段"]
PhaseSystems --> InitSystems["初始化系统"]
InitSystems --> Freeze["冻结IoC容器"]
Freeze --> Ready["进入Ready阶段"]

图表来源

章节来源

模块间通信：事件驱动的松耦合

类型化事件：EventBus提供基于类型的Send/Register/UnRegister，模块通过事件发布/订阅实现解耦
典型场景：设置系统在应用设置前后发送事件；UI路由器在页面切换前后发送事件

sequenceDiagram
participant ModA as "模块A"
participant Bus as "事件总线"
participant ModB as "模块B"
ModA->>Bus : "Send(事件A)"
Bus-->>ModB : "触发监听器"
ModB-->>Bus : "UnRegister(监听器)"

图表来源

章节来源

具体模块示例：设置模块与UI模块

设置模块（SettingsSystem）
- 负责批量/按类型应用设置，发送应用前/后事件，捕获异常并上报
UI模块（UiRouterBase）
- 提供页面栈管理、层级管理、路由守卫、UI切换处理器管道与事件

章节来源

依赖关系分析

核心层依赖抽象层，保证接口稳定
游戏层依赖核心层与抽象层，提供业务系统
平台层依赖核心与游戏抽象层，提供平台适配
源生成器作为编译期工具，不引入运行时依赖

graph LR
CoreAbst["Core.Abstractions"] --> Core["Core"]
GameAbst["Game.Abstractions"] --> Game["Game"]
CoreAbst --> Godot["Godot"]
GameAbst --> Godot
Core --> Game
CoreAbst --> GameAbst
Gen["Godot.SourceGenerators"] --> Godot

图表来源

章节来源

性能考量

初始化阶段分层：工具/模型/系统分阶段初始化，有利于资源占用与启动时间控制
生命周期去重：注册去重集合避免重复初始化与销毁
事件总线：类型化事件减少反射开销，支持异步处理
UI切换：前置与后置阶段分离，避免阻塞主线程

章节来源

故障排查指南

阶段转换异常：检查架构配置的严格阶段校验与允许的阶段转换表
注册时机错误：在Ready之后仍尝试注册组件会抛出异常，需在Install或BeforeReady阶段完成
销毁异常：单个组件销毁异常不会影响整体销毁流程，但会记录错误日志
事件未触发：确认事件监听器已注册且事件类型一致

章节来源

结论

GFramework的模块化架构通过清晰的模块边界、统一的生命周期管理与事件驱动的通信机制，实现了高内聚、低耦合的系统设计。遵循本文的最佳实践，可在复杂项目中保持模块的独立性与演进速度，同时降低集成风险。

附录

测试策略建议
- 模块独立测试：对模块内的系统与工具进行单元测试，模拟Install与Initialize流程
- 集成测试：通过Mock事件总线与IoC容器，验证模块间事件交互与阶段流转
- 平台适配测试：在Godot环境下验证模块的节点绑定与生命周期钩子
维护建议
- 严格遵守模块边界，避免跨模块直接依赖
- 通过事件总线传递消息，减少硬编码耦合
- 定期重构：拆分过大的模块，提炼公共工具与系统
- 文档与契约：保持抽象层接口稳定，逐步演进实现层

15 KiB Raw Blame History Unescape Escape

模块化架构

目录

引言

项目结构

核心组件

架构总览

详细组件分析

模块边界与设计原则

模块安装与卸载流程

模块内系统与工具组织

模块间通信：事件驱动的松耦合

具体模块示例：设置模块与UI模块

依赖关系分析

性能考量

故障排查指南

结论

附录

15 KiB

Raw Blame History