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]
12 KiB
12 KiB
路径扩展功能
**本文档引用的文件** - [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 体验
章节来源
架构概览
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
图表来源
路径转换流程
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 类展示了路径扩展在实际文件操作中的应用：
删除操作流程
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
图表来源
章节来源
场景路径管理
虽然 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 框架提供了可靠的路径处理基础设施，确保了路径操作的一致性和安全性。