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

ArchitectureAnchor锚点机制

**本文档引用的文件** - [ArchitectureAnchor.cs](file://GFramework.Godot/architecture/ArchitectureAnchor.cs) - [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs) - [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs) - [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs) - [NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs) - [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs) - [ArchitectureConstants.cs](file://GFramework.Core/architecture/ArchitectureConstants.cs) - [ArchitecturePhase.cs](file://GFramework.Core.Abstractions/enums/ArchitecturePhase.cs) - [GFrameworkConstants.cs](file://GFramework.Core/constants/GFrameworkConstants.cs) - [README.md](file://GFramework.Godot/README.md)

引言

ArchitectureAnchor是GFramework.Godot模块中实现架构与Godot生命周期绑定的核心机制。该机制通过在Godot场景树中创建一个专门的锚点节点，实现了架构组件与Godot引擎生命周期的无缝集成，确保了资源的正确管理和生命周期的完整性。

本文档深入解析ArchitectureAnchor的设计原理、实现细节和最佳实践，帮助开发者理解和正确使用这一关键机制。

项目结构

GFramework.Godot架构锚点机制涉及以下关键文件：

graph TB
subgraph "Godot架构层"
AA[AbstractArchitecture.cs]
AA1[AbstractGodotModule.cs]
AA2[IGodotModule.cs]
AA3[ArchitectureAnchor.cs]
end
subgraph "核心架构层"
AC[Architecture.cs]
AC1[ArchitectureConstants.cs]
AC2[ArchitecturePhase.cs]
end
subgraph "扩展方法层"
NE[NodeExtensions.cs]
end
subgraph "常量定义层"
GC[GFrameworkConstants.cs]
end
AA --> AA3
AA --> NE
AA --> AC
AC --> AC1
AC --> AC2
AA3 --> NE
AA3 --> GC

图表来源

章节来源

核心组件

ArchitectureAnchor机制由四个核心组件构成：

1. ArchitectureAnchor锚点节点

职责: 作为Godot场景树中的根节点，绑定架构生命周期
功能: 提供退出回调绑定和自动清理机制
特点: 轻量级设计，专注于生命周期管理

2. AbstractArchitecture架构基类

职责: 管理架构初始化、生命周期绑定和模块安装
功能: 创建锚点节点、绑定Godot生命周期、管理模块扩展
特点: 支持异步初始化和模块化架构设计

3. AbstractGodotModule模块基类

职责: 定义Godot模块的标准行为和接口
功能: 提供模块安装、附加、分离的生命周期方法
特点: 强类型设计，支持架构阶段感知

4. NodeExtensions节点扩展

职责: 提供节点操作的扩展方法
功能: 等待就绪、安全操作、延迟调用等
特点: 类型安全，错误处理完善

章节来源

架构概览

ArchitectureAnchor机制实现了架构与Godot生命周期的深度绑定：

sequenceDiagram
participant Engine as Godot引擎
participant Anchor as ArchitectureAnchor
participant Arch as AbstractArchitecture
participant Module as Godot模块
participant Tree as SceneTree
Engine->>Arch : 初始化架构
Arch->>Arch : 生成锚点名称
Arch->>Tree : 创建锚点节点
Arch->>Anchor : 绑定销毁回调
Tree->>Anchor : 添加到场景树
Arch->>Module : 安装模块
Module->>Anchor : 添加到锚点
Anchor->>Engine : 监听退出事件
Engine->>Anchor : 场景树销毁
Anchor->>Arch : 执行销毁回调
Arch->>Module : 分离模块
Module->>Engine : 清理资源

图表来源

该机制的关键优势包括：

自动生命周期管理: 锚点节点自动处理架构销毁时的清理工作
类型安全: 强类型接口确保编译时错误检测
模块化设计: 支持动态安装和卸载Godot模块
异步支持: 完整的异步初始化和等待机制

详细组件分析

ArchitectureAnchor锚点节点分析

ArchitectureAnchor是最核心的组件，实现了架构与Godot生命周期的绑定：

classDiagram
class ArchitectureAnchor {
-Action _onExit
+Bind(onExit) void
+_ExitTree() void
}
class Node {
<<Godot基类>>
+Name string
+CallDeferred(method) void
+IsInsideTree() bool
}
ArchitectureAnchor --|> Node : 继承
ArchitectureAnchor --> Action : 使用

图表来源

ArchitectureAnchor.cs

核心功能实现

回调绑定机制
- Bind(Action onExit)方法提供退出回调绑定
- 支持重复绑定警告，防止意外覆盖
- 确保资源清理的完整性
生命周期管理
- _ExitTree()方法在节点移除时自动调用
- 原子性执行回调，避免竞态条件
- 清理引用，防止内存泄漏

章节来源

ArchitectureAnchor.cs

AbstractArchitecture架构基类分析

AbstractArchitecture负责整体架构的生命周期管理：

classDiagram
class AbstractArchitecture {
-IGodotModule[] _extensions
-ArchitectureAnchor _anchor
-string _architectureAnchorName
-bool _destroyed
+InstallGodotModule~TModule~(module) Task
+Destroy() void
-AttachToGodotLifecycle() void
#InstallModules() void*
}
class Architecture {
<<Core基类>>
+Initialize() void
+InitializeAsync() Task
+Destroy() void
#Init() void*
}
class IGodotModule {
<<接口>>
+Node Node
+Install(architecture) void
+OnAttach(architecture) void
+OnDetach() void
}
AbstractArchitecture --|> Architecture : 继承
AbstractArchitecture --> ArchitectureAnchor : 使用
AbstractArchitecture --> IGodotModule : 管理

图表来源

AbstractArchitecture.cs

关键实现细节

锚点命名策略
- 使用框架名称、架构类型和哈希码生成唯一标识
- 格式：__{FrameworkName}__{ArchitectureType}__{HashCode}__ArchitectureAnchor__
- 确保在场景树中的唯一性和可识别性
Godot生命周期绑定
- 检查主循环是否存在SceneTree
- 防止重复挂载，支持热重载场景
- 使用CallDeferred确保线程安全
模块管理机制
- 维护已安装模块列表
- 支持异步模块安装
- 完整的模块生命周期管理

章节来源

NodeExtensions等待机制分析

NodeExtensions提供了关键的等待和异步操作支持：

flowchart TD
Start([等待就绪开始]) --> CheckTree["检查节点是否在场景树中"]
CheckTree --> InsideTree{"是否在场景树中?"}
InsideTree --> |是| ReturnNow["立即返回"]
InsideTree --> |否| WaitSignal["等待Ready信号"]
WaitSignal --> SignalReceived["收到Ready信号"]
SignalReceived --> ReturnComplete["返回完成"]
ReturnNow --> End([等待就绪结束])
ReturnComplete --> End

图表来源

NodeExtensions.cs

WaitUntilReady实现原理

智能等待逻辑
- 如果节点已在场景树中，立即返回
- 如果节点尚未就绪，等待Ready信号
- 使用Godot的信号系统实现非阻塞等待
异步模块安装流程

sequenceDiagram participant Arch as AbstractArchitecture participant Anchor as ArchitectureAnchor participant Module as Godot模块 Arch->>Module : Install(this) Arch->>Anchor : WaitUntilReady() Anchor-->>Arch : 就绪信号 Arch->>Anchor : CallDeferred(AddChild) Arch->>Module : OnAttach(this) Arch->>Arch : 添加到扩展列表


**图表来源**
- [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L108-L112)
- [NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs#L52-L55)

**章节来源**
- [NodeExtensions.cs](file://GFramework.Godot/extensions/NodeExtensions.cs#L48-L55)
- [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L108-L112)

### 架构阶段管理分析

ArchitectureAnchor机制与架构阶段系统紧密集成：

```mermaid
stateDiagram-v2
[*] --> None
None --> BeforeUtilityInit
BeforeUtilityInit --> AfterUtilityInit
AfterUtilityInit --> BeforeModelInit
BeforeModelInit --> AfterModelInit
AfterModelInit --> BeforeSystemInit
BeforeSystemInit --> AfterSystemInit
AfterSystemInit --> Ready
Ready --> Destroying
Destroying --> Destroyed
Destroyed --> [*]
state Ready {
[*] --> WaitingForAnchor
WaitingForAnchor --> AnchorAttached
AnchorAttached --> ModulesInstalled
}

图表来源

章节来源

依赖关系分析

ArchitectureAnchor机制的依赖关系如下：

graph TB
subgraph "外部依赖"
GD[Godot引擎]
GFC[GFrameworkConstants]
end
subgraph "核心依赖"
AA[AbstractArchitecture]
AA3[ArchitectureAnchor]
AC[Architecture]
NE[NodeExtensions]
end
subgraph "接口依赖"
IGM[IGodotModule]
IAP[IArchitecturePhaseAware]
end
GD --> AA3
GFC --> AA
AA --> AA3
AA --> AC
AA3 --> NE
AA -.-> IGM
AC -.-> IAP

图表来源

关键依赖关系

Godot引擎集成
- 依赖SceneTree进行场景树操作
- 使用CallDeferred确保线程安全
- 通过Ready信号实现异步等待
框架常量依赖
- 使用GFrameworkConstants确保命名一致性
- 支持框架标识和版本管理
接口契约依赖
- IGodotModule定义模块标准
- IArchitecturePhaseAware支持阶段感知
- 强类型设计确保编译时安全

章节来源

性能考虑

ArchitectureAnchor机制在设计时充分考虑了性能优化：

1. 内存管理优化

使用弱引用避免循环引用
原子性操作防止竞态条件
及时清理回调引用防止内存泄漏

2. 线程安全保证

所有场景树操作使用CallDeferred
避免在渲染线程中进行阻塞操作
支持多线程环境下的安全访问

3. 初始化性能优化

延迟创建锚点节点
智能等待机制避免不必要的阻塞
模块安装支持异步处理

故障排除指南

常见问题及解决方案

1. 锚点重复创建问题

症状: 场景切换后出现多个锚点节点原因: 重复调用Initialize或热重载场景 解决方案:

检查场景树中是否已存在同名锚点
确保正确销毁旧架构实例
使用唯一命名策略避免冲突

2. 模块安装失败问题

症状: 模块无法正常安装或就绪原因: 锚点未正确初始化或等待超时 解决方案:

验证锚点名称生成逻辑
检查WaitUntilReady调用时机
确保模块安装在正确的架构阶段

3. 资源清理不完整问题

症状: 场景切换后资源未正确释放原因: 退出回调未执行或异常中断 解决方案:

检查Bind方法调用是否成功
验证_destroyed标志位状态
确保模块OnDetach实现正确

4. 异步操作死锁问题

症状: 等待操作无法正常完成原因: 错误的异步调用模式 解决方案:

使用WaitUntilReady而非阻塞等待
确保CallDeferred的正确使用
验证Godot信号系统的完整性

章节来源

结论

ArchitectureAnchor锚点机制是GFramework.Godot架构设计的核心创新，它成功解决了架构组件与Godot引擎生命周期绑定的技术难题。通过精心设计的锚点节点、智能的等待机制和完善的生命周期管理，该机制为开发者提供了强大而可靠的架构基础。

主要优势总结

无缝集成: 架构生命周期与Godot生命周期完全同步
类型安全: 强类型设计确保编译时错误检测
模块化: 支持动态模块安装和卸载
异步支持: 完整的异步初始化和等待机制
性能优化: 线程安全和内存管理优化

最佳实践建议

正确使用锚点命名: 确保唯一性和可识别性
及时清理资源: 遵循架构销毁流程
合理使用异步: 利用WaitUntilReady避免阻塞
模块化设计: 按功能分组组织Godot模块
错误处理: 实现完善的异常处理机制

通过深入理解ArchitectureAnchor机制的设计原理和实现细节，开发者可以更好地利用GFramework.Godot框架的优势，构建高质量的Godot游戏应用。

15 KiB Raw Blame History Unescape Escape

ArchitectureAnchor锚点机制

目录

引言

项目结构

核心组件

1. ArchitectureAnchor锚点节点

2. AbstractArchitecture架构基类

3. AbstractGodotModule模块基类

4. NodeExtensions节点扩展

架构概览

详细组件分析

ArchitectureAnchor锚点节点分析

核心功能实现

AbstractArchitecture架构基类分析

关键实现细节

NodeExtensions等待机制分析

WaitUntilReady实现原理

依赖关系分析

关键依赖关系

性能考虑

1. 内存管理优化

2. 线程安全保证

3. 初始化性能优化

故障排除指南

常见问题及解决方案

1. 锚点重复创建问题

2. 模块安装失败问题

3. 资源清理不完整问题

4. 异步操作死锁问题

结论

主要优势总结

最佳实践建议

15 KiB

Raw Blame History