mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-25 21:34:28 +08:00

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

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

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

12 KiB

Raw Blame History

路径扩展功能

**本文档引用的文件** - [GodotPathExtensions.cs](file://GFramework.Godot/extensions/GodotPathExtensions.cs) - [README.md](file://GFramework.Godot/extensions/README.md) - [GodotFileStorage.cs](file://GFramework.Godot/storage/GodotFileStorage.cs) - [GodotSceneRegistry.cs](file://GFramework.Godot/scene/GodotSceneRegistry.cs) - [IGodotSceneRegistry.cs](file://GFramework.Godot/scene/IGodotSceneRegistry.cs) - [README.md](file://GFramework.Godot/README.md)

简介

GodotPathExtensions 类是 GFramework.Godot 框架中的一个轻量级路径处理扩展，专门用于识别和验证 Godot 引擎的虚拟路径格式。该类提供了三个核心方法来判断路径类型：IsUserPath() 用于识别用户数据路径（user://），IsResPath() 用于识别资源路径（res://），以及 IsGodotPath() 用于判断是否为 Godot 虚拟路径。

在 Godot 引擎中，路径系统分为三类：

res:// - 资源路径：指向游戏包内的资源文件
user:// - 用户数据路径：指向用户特定的数据存储位置
绝对/相对文件系统路径：指向操作系统文件系统中的文件

项目结构

graph TB
subgraph "GFramework.Godot 扩展模块"
A[Extensions] --> B[GodotPathExtensions]
A --> C[NodeExtensions]
A --> D[SignalFluentExtensions]
A --> E[UnRegisterExtension]
B --> F[路径判断扩展]
C --> G[节点生命周期]
C --> H[节点查询]
C --> I[场景树操作]
C --> J[输入控制]
C --> K[调试工具]
D --> L[SignalBuilder]
D --> M[信号连接系统]
E --> N[事件管理]
end
subgraph "路径处理相关组件"
O[GodotFileStorage] --> P[路径转换]
O --> Q[文件操作]
R[GodotSceneRegistry] --> S[场景管理]
end
B --> O
B --> R

图表来源

章节来源

核心组件

GodotPathExtensions 类

GodotPathExtensions 是一个静态类，提供了三个核心的路径判断方法：

方法概览

方法名	功能描述	参数	返回值	使用场景
IsUserPath	判断是否为 Godot 用户数据路径	`string path`	`bool`	用户数据文件验证
IsResPath	判断是否为 Godot 资源路径	`string path`	`bool`	资源文件验证
IsGodotPath	判断是否为 Godot 虚拟路径	`string path`	`bool`	通用路径类型判断

实现特点

空值安全：所有方法都检查输入字符串是否为 null 或空
前缀匹配：使用字符串前缀匹配来识别路径类型
性能优化：采用简单的字符串操作，时间复杂度为 O(1)
类型安全：作为扩展方法使用，提供流畅的 API 体验

章节来源

GodotPathExtensions.cs

架构概览

sequenceDiagram
participant Client as 客户端代码
participant PathExt as GodotPathExtensions
participant FileStorage as GodotFileStorage
participant FileSystem as 文件系统
Client->>PathExt : 调用 IsGodotPath(path)
PathExt->>PathExt : 检查 IsUserPath() 或 IsResPath()
PathExt-->>Client : 返回路径类型判断结果
Client->>FileStorage : 调用 ToAbsolutePath(key)
FileStorage->>PathExt : 检查 IsGodotPath()
alt 路径为 Godot 虚拟路径
PathExt-->>FileStorage : 返回 true
FileStorage->>FileSystem : 使用 FileAccess 操作
else 普通文件系统路径
PathExt-->>FileStorage : 返回 false
FileStorage->>FileSystem : 使用 System.IO 操作
end

图表来源

详细组件分析

路径类型判断机制

flowchart TD
Start([开始路径判断]) --> ValidateInput["验证输入参数"]
ValidateInput --> CheckNull{"输入是否为空?"}
CheckNull --> |是| ReturnFalse["返回 false"]
CheckNull --> |否| CheckPrefix["检查路径前缀"]
CheckPrefix --> CheckUser{"是否以 'user://' 开头?"}
CheckUser --> |是| ReturnTrueUser["返回 true (用户路径)"]
CheckUser --> |否| CheckRes{"是否以 'res://' 开头?"}
CheckRes --> |是| ReturnTrueRes["返回 true (资源路径)"]
CheckRes --> |否| ReturnFalse["返回 false"]
ReturnTrueUser --> End([结束])
ReturnTrueRes --> End
ReturnFalse --> End
ReturnFalse --> End
CheckNull --> End
ValidateInput --> End

图表来源

GodotPathExtensions.cs

路径转换流程

GodotFileStorage 类展示了如何在实际应用中使用路径扩展功能：

flowchart TD
InputKey["输入存储键"] --> CleanPath["清理路径格式<br/>替换反斜杠为正斜杠"]
CleanPath --> ValidateSegments["验证路径段<br/>检查 '..' 操作符"]
ValidateSegments --> CheckGodotPath{"是否为 Godot 路径?"}
CheckGodotPath --> |是| ReturnDirect["直接返回 Godot 路径"]
CheckGodotPath --> |否| SplitSegments["分割路径段"]
SplitSegments --> SanitizeSegments["清理无效文件名字符"]
SanitizeSegments --> BuildPath["构建绝对路径"]
BuildPath --> CreateDir["创建目录(如需要)"]
CreateDir --> ReturnPath["返回最终路径"]
ReturnDirect --> End([结束])
ReturnPath --> End

图表来源

GodotFileStorage.cs

章节来源

GodotFileStorage.cs

文件存储操作集成

GodotFileStorage 类展示了路径扩展在实际文件操作中的应用：

删除操作流程

sequenceDiagram
participant Client as 客户端
participant Storage as GodotFileStorage
participant PathExt as GodotPathExtensions
participant FS as 文件系统
Client->>Storage : Delete(key)
Storage->>Storage : ToAbsolutePath(key)
Storage->>PathExt : IsGodotPath()
PathExt-->>Storage : 返回路径类型
alt Godot 路径
Storage->>FS : DirAccess.RemoveAbsolute(path)
else 普通路径
Storage->>FS : File.Delete(path)
end

图表来源

章节来源

GodotFileStorage.cs

场景路径管理

虽然 GodotPathExtensions 本身不直接处理场景路径，但它与场景管理系统协同工作：

场景注册表架构

classDiagram
class GodotSceneRegistry {
+Register(key, scene)
+Get(key) PackedScene
+Contains(key) bool
+Remove(key) bool
}
class IGodotSceneRegistry {
<<interface>>
+Register(key, scene)
+Get(key) PackedScene
+Contains(key) bool
+Remove(key) bool
}
class KeyValueRegistryBase {
<<abstract>>
+Register(key, value)
+Get(key) T
+Contains(key) bool
+Remove(key) bool
}
class PackedScene {
+Resource
}
GodotSceneRegistry --|> KeyValueRegistryBase
GodotSceneRegistry ..|> IGodotSceneRegistry
GodotSceneRegistry --> PackedScene : stores

图表来源

章节来源

依赖关系分析

graph LR
subgraph "核心依赖"
A[GodotPathExtensions] --> B[System.String]
A --> C[扩展方法机制]
end
subgraph "存储层依赖"
D[GodotFileStorage] --> A
D --> E[FileAccess]
D --> F[Directory]
D --> G[File]
end
subgraph "场景管理层依赖"
H[GodotSceneRegistry] --> I[PackedScene]
H --> J[StringComparer]
end
subgraph "外部系统"
K[Godot 引擎] --> E
K --> F
K --> G
K --> I
end
A --> D
A --> H

图表来源

章节来源

性能考虑

时间复杂度分析

IsUserPath(): O(1) - 字符串前缀比较
IsResPath(): O(1) - 字符串前缀比较
IsGodotPath(): O(1) - 两次前缀比较的逻辑或运算

内存使用

所有方法都是纯函数，不创建额外的内存分配
字符串操作在栈上完成，无堆分配
扩展方法调用开销最小

最佳实践建议

批量路径判断：对于大量路径的判断，优先使用 IsGodotPath() 统一处理
缓存结果：对于重复使用的路径判断结果，考虑在业务层缓存
避免不必要的转换：直接使用 Godot 路径格式，避免不必要的路径转换

故障排除指南

常见问题及解决方案

问题1：路径判断总是返回 false

可能原因：

输入路径为 null 或空字符串
路径格式不正确（缺少协议前缀）

解决方案：

// 确保输入验证
if (!string.IsNullOrEmpty(path) && path.StartsWith("res://"))
{
    // 处理资源路径
}

问题2：路径转换异常

可能原因：

路径包含非法字符 '..'
路径格式不符合要求

解决方案：

// 使用框架提供的安全转换
try
{
    var absolutePath = ToAbsolutePath(key);
}
catch (ArgumentException ex)
{
    // 处理非法路径
    Logger.Error($"非法存储键: {ex.Message}");
}

问题3：文件操作权限错误

可能原因：

用户数据路径权限不足
文件已被其他进程占用

解决方案：

// 检查路径类型并采取相应措施
if (path.IsUserPath())
{
    // 处理用户数据路径权限
}
else if (path.IsResPath())
{
    // 处理资源路径访问
}

章节来源

结论

GodotPathExtensions 类虽然功能简单，但在 GFramework.Godot 框架中扮演着重要的角色。它提供了轻量级、高效的路径类型识别功能，为整个框架的路径处理提供了基础支撑。

主要优势

简洁高效：三个方法覆盖了所有主要的路径类型判断需求
零依赖：仅依赖标准库，无外部依赖
易于使用：扩展方法语法提供流畅的 API 体验
性能优异：O(1) 时间复杂度，适合高频调用场景

应用场景

文件存储系统：区分 Godot 虚拟路径和普通文件系统路径
资源管理：识别和处理不同类型的游戏资源
场景加载：验证场景文件路径的有效性
配置管理：判断配置文件的存储位置类型

通过与其他组件（如 GodotFileStorage、GodotSceneRegistry）的协作，GodotPathExtensions 为整个 GFramework.Godot 框架提供了可靠的路径处理基础设施，确保了路径操作的一致性和安全性。

12 KiB Raw Blame History Unescape Escape

路径扩展功能

目录

简介

项目结构

核心组件

GodotPathExtensions 类

方法概览

实现特点

架构概览

详细组件分析

路径类型判断机制

路径转换流程

文件存储操作集成

删除操作流程

场景路径管理

场景注册表架构

依赖关系分析

性能考虑

时间复杂度分析

内存使用

最佳实践建议

故障排除指南

常见问题及解决方案

问题1：路径判断总是返回 false

问题2：路径转换异常

问题3：文件操作权限错误

结论

主要优势

应用场景

12 KiB

Raw Blame History