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

18 KiB

Raw Blame History

AbstractArchitecture基类

**本文档引用的文件** - [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs) - [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs) - [ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.cs) - [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs) - [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs) - [godot-integration.md](file://docs/tutorials/godot-integration.md) - [architecture-patterns.md](file://docs/best-practices/architecture-patterns.md)

简介

AbstractArchitecture是GFramework中Godot平台特定的架构基类，它继承自Core模块的Architecture基类，专门为Godot引擎提供了生命周期管理和模块化架构支持。该类通过与Godot场景树的深度集成，实现了架构组件的自动生命周期管理和资源清理。

该基类的核心价值在于：

Godot生命周期绑定：通过ArchitectureAnchor节点将架构与Godot场景树生命周期紧密绑定
模块化架构系统：支持IGodotModule接口的模块化扩展机制
自动资源管理：确保架构销毁时所有相关资源得到正确清理
类型安全的模块安装：提供强类型约束的模块安装和管理机制

项目结构

GFramework采用分层架构设计，AbstractArchitecture位于Godot特定层：

graph TB
subgraph "Core架构层"
CoreArch[Architecture基类]
CoreContext[ArchitectureContext]
CoreServices[ArchitectureServices]
end
subgraph "Godot架构层"
AbstractArch[AbstractArchitecture]
ArchAnchor[ArchitectureAnchor]
GodotModule[IGodotModule]
AbstractGodotMod[AbstractGodotModule]
end
subgraph "应用层"
GameArch[游戏架构实现]
GameModule[游戏模块]
end
CoreArch --> AbstractArch
AbstractArch --> ArchAnchor
AbstractArch --> GodotModule
GodotModule --> AbstractGodotMod
AbstractArch --> GameArch
GodotModule --> GameModule

图表来源

章节来源

核心组件

主要特性概述

AbstractArchitecture继承了Core架构的所有核心功能，并增加了Godot特定的扩展能力：

特性	描述	实现位置
架构初始化	完整的架构初始化流程，包括模块安装	Init方法
Godot生命周期绑定	通过ArchitectureAnchor节点绑定场景树生命周期	AttachToGodotLifecycle方法
模块安装系统	支持IGodotModule接口的模块安装和管理	InstallGodotModule方法
资源清理机制	架构销毁时自动清理所有已安装模块	Destroy方法
根节点访问	提供受保护的ArchitectureRoot属性访问	ArchitectureRoot属性

章节来源

AbstractArchitecture.cs

架构概览

AbstractArchitecture的架构设计体现了良好的分层原则和依赖倒置：

classDiagram
class Architecture {
<<abstract>>
+Initialize()
+InitializeAsync()
+Destroy()
+RegisterSystem()
+RegisterModel()
+RegisterUtility()
#Init()
#EnterPhase()
}
class AbstractArchitecture {
<<abstract>>
-_extensions : IGodotModule[]
-_anchor : ArchitectureAnchor
-_architectureAnchorName : string
-_destroyed : bool
+ArchitectureRoot : Node
#Init()
#InstallModules()
-AttachToGodotLifecycle()
+InstallGodotModule()
+Destroy()
}
class ArchitectureAnchor {
-_onExit : Action
+Bind()
+_ExitTree()
}
class IGodotModule {
<<interface>>
+Node : Node
+Install()
+OnAttach()
+OnDetach()
}
class AbstractGodotModule {
<<abstract>>
+Node : Node
+Install()
+OnAttach()
+OnDetach()
+OnPhase()
}
Architecture <|-- AbstractArchitecture
AbstractArchitecture --> ArchitectureAnchor : "使用"
AbstractArchitecture --> IGodotModule : "管理"
IGodotModule <|-- AbstractGodotModule
AbstractGodotModule --> Architecture : "回调"

图表来源

详细组件分析

架构初始化流程

AbstractArchitecture的初始化流程是一个精心设计的多阶段过程：

sequenceDiagram
participant Client as "客户端代码"
participant Arch as "AbstractArchitecture"
participant Anchor as "ArchitectureAnchor"
participant Core as "Core Architecture"
Client->>Arch : 调用Initialize()
Arch->>Arch : 生成架构锚点名称
Arch->>Arch : AttachToGodotLifecycle()
Arch->>Anchor : 创建并绑定锚点
Arch->>Arch : InstallModules()
Arch->>Core : 调用基类Init()
Core->>Core : 初始化上下文和环境
Core->>Core : 调用用户Init()
Core->>Core : 初始化组件(工具→模型→系统)
Core->>Core : 进入Ready阶段
Core-->>Client : 初始化完成
Note over Arch,Anchor : 架构与Godot生命周期绑定完成

图表来源

初始化阶段详解

锚点创建阶段：生成唯一的架构锚点名称，确保在场景树中不会冲突
生命周期绑定阶段：通过ArchitectureAnchor节点监听场景树销毁事件
模块安装阶段：调用子类实现的InstallModules方法
核心初始化阶段：委托给基类Architecture执行完整的初始化流程

章节来源

InstallModules抽象方法

InstallModules是AbstractArchitecture的核心扩展点，设计目的是：

flowchart TD
Start([调用InstallModules]) --> CheckInit{"架构锚点已初始化?"}
CheckInit --> |否| ThrowError["抛出InvalidOperationException"]
CheckInit --> |是| LoopModules["遍历模块列表"]
LoopModules --> InstallModule["调用module.Install(this)"]
InstallModule --> WaitReady["等待锚点准备就绪"]
WaitReady --> AddChild["将模块节点添加为锚点子节点"]
AddChild --> CallAttach["调用module.OnAttach(this)"]
CallAttach --> AddToList["添加到扩展列表"]
AddToList --> NextModule{"还有模块?"}
NextModule --> |是| LoopModules
NextModule --> |否| Complete([安装完成])
ThrowError --> End([结束])
Complete --> End

图表来源

AbstractArchitecture.cs

设计要求和约束

必须在Init方法中调用：确保架构锚点已正确初始化
类型安全：只能安装实现IGodotModule接口的模块
异步等待：必须等待锚点准备就绪后再添加节点
生命周期管理：模块必须正确实现OnAttach和OnDetach方法

章节来源

AbstractArchitecture.cs

架构根节点获取机制

AbstractArchitecture提供了受保护的ArchitectureRoot属性：

flowchart TD
GetRoot[获取ArchitectureRoot] --> CheckAnchor{"_anchor是否为null?"}
CheckAnchor --> |是| ThrowException["抛出InvalidOperationException"]
CheckAnchor --> |否| ReturnRoot["返回_anchor引用"]
ThrowException --> End([结束])
ReturnRoot --> End

图表来源

AbstractArchitecture.cs

异常处理策略

未初始化异常：当架构尚未完成初始化时访问根节点会抛出异常
设计意图：强制开发者在正确的时机访问架构根节点
调试友好：异常信息明确指示架构未准备就绪

章节来源

AbstractArchitecture.cs

架构销毁过程

AbstractArchitecture的销毁过程确保了资源的完整清理：

flowchart TD
Start([调用Destroy]) --> CheckDestroyed{"已销毁标记?"}
CheckDestroyed --> |是| ReturnEarly["直接返回"]
CheckDestroyed --> |否| SetFlag["设置_destroyed=true"]
SetFlag --> LoopExtensions["遍历_extensions列表"]
LoopExtensions --> CallDetach["调用ext.OnDetach()"]
CallDetach --> NextExt{"还有扩展?"}
NextExt --> |是| LoopExtensions
NextExt --> |否| ClearList["清空扩展列表"]
ClearList --> CallBaseDestroy["调用base.Destroy()"]
CallBaseDestroy --> End([销毁完成])
ReturnEarly --> End

图表来源

AbstractArchitecture.cs

资源清理策略

模块级清理：逐个调用已安装模块的OnDetach方法
列表清理：清空模块列表，防止重复销毁
基类清理：委托给基类Architecture执行核心组件清理
防重复销毁：通过_destroyed标志防止重复销毁操作

章节来源

AbstractArchitecture.cs

Godot生命周期绑定机制

AbstractArchitecture通过ArchitectureAnchor实现了与Godot场景树的深度集成：

sequenceDiagram
participant Engine as "Godot引擎"
participant SceneTree as "SceneTree"
participant Anchor as "ArchitectureAnchor"
participant Arch as "AbstractArchitecture"
participant Modules as "已安装模块"
Engine->>SceneTree : 初始化主循环
SceneTree->>Arch : 调用AttachToGodotLifecycle()
Arch->>Anchor : 创建ArchitectureAnchor节点
Arch->>Anchor : 绑定Destroy回调
Anchor->>SceneTree : 添加到场景树
Note over Engine,SceneTree : 架构与Godot生命周期绑定
Engine->>SceneTree : 场景树销毁
SceneTree->>Anchor : _ExitTree()回调
Anchor->>Arch : 调用绑定的Destroy()
Arch->>Modules : 逐个调用OnDetach()
Arch->>Arch : 清理扩展列表
Arch->>SceneTree : 基类Destroy()

图表来源

绑定机制特点

延迟绑定：使用CallDeferred确保在下一帧绑定，避免线程安全问题
防重复绑定：检查场景树中是否已存在同名节点
自动清理：通过_exitTree回调自动触发架构销毁
类型安全：通过泛型约束确保模块实现正确的接口

章节来源

依赖关系分析

AbstractArchitecture的依赖关系体现了清晰的分层架构：

graph TB
subgraph "外部依赖"
Godot[Godot引擎]
CoreAbstractions[GFramework.Core.Abstractions]
end
subgraph "核心层"
CoreArch[Architecture基类]
CoreContext[ArchitectureContext]
CoreServices[ArchitectureServices]
end
subgraph "Godot层"
AbstractArch[AbstractArchitecture]
ArchAnchor[ArchitectureAnchor]
IGodotModule[IGodotModule接口]
AbstractGodotMod[AbstractGodotModule]
end
subgraph "应用层"
GameArch[游戏架构实现]
GameModule[游戏模块]
end
Godot --> ArchAnchor
CoreAbstractions --> CoreArch
CoreArch --> AbstractArch
AbstractArch --> ArchAnchor
AbstractArch --> IGodotModule
IGodotModule --> AbstractGodotMod
AbstractArch --> GameArch
IGodotModule --> GameModule

图表来源

关键依赖关系

继承关系：AbstractArchitecture → Architecture，获得完整的架构管理能力
组合关系：AbstractArchitecture组合了ArchitectureAnchor和模块列表
接口实现：IGodotModule定义了Godot模块的标准接口
Godot集成：直接依赖Godot引擎的节点系统和场景树管理

章节来源

性能考虑

初始化性能优化

AbstractArchitecture在初始化过程中采用了多项性能优化策略：

延迟绑定：使用CallDeferred避免阻塞主线程
去重机制：通过HashSet确保组件注册的原子性和唯一性
阶段化初始化：按工具→模型→系统的顺序初始化，减少依赖问题
异步支持：支持异步组件初始化，提高响应性

内存管理

弱引用模式：模块列表使用List而非Dictionary，减少内存开销
及时清理：销毁时立即清空模块列表，避免内存泄漏
生命周期感知：所有组件都实现了IDisposable接口，确保资源正确释放

最佳实践建议

模块大小：每个Godot模块应该职责单一，避免过度复杂的节点树
节点层级：合理控制节点层级深度，避免过深的场景树结构
资源管理：模块内部应该妥善管理自己的资源，避免内存泄漏

故障排除指南

常见问题和解决方案

1. "架构根节点未就绪"异常

症状：访问ArchitectureRoot属性时抛出InvalidOperationException

原因：

在架构初始化完成前访问根节点
架构已被销毁后再次尝试访问

解决方案：

确保在Initialize()或InitializeAsync()完成后访问根节点
避免在Destroy()后重新使用架构实例

2. 模块安装失败

症状：InstallGodotModule抛出InvalidOperationException

原因：

在模块安装前没有正确初始化架构
模块节点添加到场景树失败

解决方案：

确保在InstallModules中调用InstallGodotModule
检查模块的Node属性是否正确实现

3. 资源清理不完全

症状：游戏退出后仍有资源未释放

原因：

模块未正确实现OnDetach方法
模块内部持有静态引用

解决方案：

确保每个模块都正确实现OnDetach
检查模块内部是否有静态引用或事件订阅

章节来源

结论

AbstractArchitecture基类成功地将Core架构的通用功能与Godot引擎的特定需求相结合，提供了一个强大而灵活的架构框架。其主要优势包括：

完整的生命周期管理：通过ArchitectureAnchor实现了与Godot场景树的深度集成
模块化设计：支持IGodotModule接口的模块化扩展机制
类型安全：提供强类型约束，减少运行时错误
资源管理：自动化的资源清理机制确保内存安全
易于使用：简洁的API设计降低了使用复杂度

该基类为Godot游戏开发提供了一个坚实的基础，开发者可以基于此构建复杂的游戏架构，同时享受GFramework带来的开发效率和可靠性提升。

附录

使用示例

以下是一个完整的AbstractArchitecture使用示例：

// 1. 创建游戏架构类
public class MyGameArchitecture : AbstractArchitecture
{
    protected override void Init()
    {
        // 注册核心组件
        RegisterModel(new PlayerModel());
        RegisterSystem(new PlayerControllerSystem());
        RegisterUtility(new AudioManager());
        
        // 调用基类Init完成核心初始化
        base.Init();
    }
    
    protected override void InstallModules()
    {
        // 安装Godot特定模块
        InstallGodotModule(new UIManager());
        InstallGodotModule(new InputManager());
        InstallGodotModule(new AudioManager());
    }
}

// 2. 创建Godot模块
[GlobalClass]
public partial class UIManager : AbstractGodotModule
{
    private Control _uiRoot;
    
    public override Node Node => this;
    
    public override void Install(IArchitecture architecture)
    {
        architecture.RegisterSystem(new UIMessageSystem());
        architecture.RegisterUtility(new UIAnimationUtility());
    }
    
    public override void OnAttach(Architecture architecture)
    {
        // 创建UI根节点
        _uiRoot = new Control();
        AddChild(_uiRoot);
        
        // 初始化UI系统
        GetSystem<UIMessageSystem>().Initialize(_uiRoot);
    }
    
    public override void OnDetach()
    {
        // 清理UI资源
        _uiRoot?.QueueFree();
        _uiRoot = null;
    }
}

最佳实践清单

模块设计
- 每个模块职责单一
- 模块间通过事件通信
- 避免模块间的直接依赖
资源管理
- 模块内部妥善管理资源
- 在OnDetach中清理所有资源
- 避免静态引用导致的内存泄漏
错误处理
- 在模块中适当处理异常
- 提供有意义的错误信息
- 确保模块的健壮性
性能优化
- 合理控制模块数量
- 优化节点层级结构
- 使用异步加载大型资源

章节来源

18 KiB Raw Blame History Unescape Escape

AbstractArchitecture基类

目录

简介

项目结构

核心组件

主要特性概述

架构概览

详细组件分析

架构初始化流程

初始化阶段详解

InstallModules抽象方法

设计要求和约束

架构根节点获取机制

异常处理策略

架构销毁过程

资源清理策略

Godot生命周期绑定机制

绑定机制特点

依赖关系分析

关键依赖关系

性能考虑

初始化性能优化

内存管理

最佳实践建议

故障排除指南

常见问题和解决方案

1. "架构根节点未就绪"异常

2. 模块安装失败

3. 资源清理不完全

结论

附录

使用示例

最佳实践清单

18 KiB

Raw Blame History