465 lines
18 KiB
Markdown
465 lines
18 KiB
Markdown
# FileSystem 文件系统模块
|
||
|
||
## 模块概述
|
||
|
||
FileSystem 是 YooAsset 资源管理系统的**文件访问抽象层**，负责统一管理不同来源的资源文件访问。该模块采用策略模式设计，通过 `IFileSystem` 接口抽象不同的文件存储策略，支持编辑器模拟、内置资源、缓存资源、WebGL 等多种场景。
|
||
|
||
### 核心职责
|
||
|
||
- 统一的文件系统接口抽象
|
||
- 资源包文件的加载和管理
|
||
- 资源清单的请求和加载
|
||
- 缓存文件的验证和清理
|
||
- 资源下载的调度和管理
|
||
|
||
---
|
||
|
||
## 设计目标
|
||
|
||
| 目标 | 说明 |
|
||
|------|------|
|
||
| **统一抽象** | 通过 IFileSystem 接口统一不同来源的文件访问 |
|
||
| **策略模式** | 可插拔的文件系统实现，支持自定义扩展 |
|
||
| **多场景支持** | 编辑器、单机、联机、WebGL 等多种运行模式 |
|
||
| **灵活配置** | 通过参数系统支持丰富的自定义配置 |
|
||
|
||
---
|
||
|
||
## 架构概念
|
||
|
||
### 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ ResourcePackage │
|
||
│ (资源包管理) │
|
||
└─────────────────────────┬───────────────────────────────┘
|
||
│
|
||
┌─────────────────────────▼───────────────────────────────┐
|
||
│ PlayModeImpl │
|
||
│ (运行模式实现) │
|
||
│ 管理多个 IFileSystem，按优先级查询 │
|
||
└─────────────────────────┬───────────────────────────────┘
|
||
│
|
||
┌─────────────────────────▼───────────────────────────────┐
|
||
│ IFileSystem │
|
||
│ (文件系统接口) │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ DefaultEditorFileSystem │ 编辑器模拟文件系统 │
|
||
│ DefaultBuildinFileSystem │ 内置资源文件系统 │
|
||
│ DefaultCacheFileSystem │ 缓存资源文件系统 │
|
||
│ DefaultUnpackFileSystem │ 解压资源文件系统 │
|
||
│ DefaultWebServerFileSystem │ WebGL 服务器文件系统 │
|
||
│ DefaultWebRemoteFileSystem │ WebGL 远程文件系统 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────────────────────▼───────────────────────────────┐
|
||
│ BundleResult │
|
||
│ (资源包加载结果) │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ AssetBundleResult │ Unity AssetBundle 加载结果 │
|
||
│ RawBundleResult │ 原生文件加载结果 │
|
||
│ VirtualBundleResult│ 虚拟资源包结果（编辑器模拟） │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 核心组件
|
||
|
||
- **IFileSystem**: 文件系统核心接口，定义所有文件操作的契约
|
||
- **FileSystemParameters**: 文件系统参数配置，支持自定义参数注入
|
||
- **BundleResult**: 资源包加载结果抽象，封装不同类型的加载结果
|
||
- **FSOperation**: 文件系统操作基类，定义异步操作的抽象
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
FileSystem/
|
||
├── Interface/ # 接口定义
|
||
│ └── IFileSystem.cs # 文件系统核心接口
|
||
│
|
||
├── Operation/ # 操作基类定义
|
||
│ ├── FSInitializeFileSystemOperation.cs # 初始化操作
|
||
│ ├── FSRequestPackageVersionOperation.cs # 请求版本操作
|
||
│ ├── FSLoadPackageManifestOperation.cs # 加载清单操作
|
||
│ ├── FSLoadBundleOperation.cs # 加载资源包操作
|
||
│ ├── FSDownloadFileOperation.cs # 下载文件操作
|
||
│ ├── FSClearCacheFilesOperation.cs # 清理缓存操作
|
||
│ ├── FSLoadAssetOperation.cs # 加载资源操作
|
||
│ ├── FSLoadAllAssetsOperation.cs # 加载所有资源操作
|
||
│ ├── FSLoadSubAssetsOperation.cs # 加载子资源操作
|
||
│ └── FSLoadSceneOperation.cs # 加载场景操作
|
||
│
|
||
├── BundleResult/ # 资源包加载结果
|
||
│ ├── BundleResult.cs # 结果基类
|
||
│ ├── AssetBundleResult/ # AssetBundle 结果实现
|
||
│ ├── RawBundleResult/ # 原生文件结果实现
|
||
│ └── VirtualBundleResult/ # 虚拟资源包结果实现
|
||
│
|
||
├── WebGame/ # WebGL 相关操作
|
||
│ └── Operation/ # WebGL 专用操作类
|
||
│
|
||
├── FileSystemParameters.cs # 文件系统参数
|
||
├── FileSystemParametersDefine.cs # 参数名称常量定义
|
||
├── FileVerifyHelper.cs # 文件校验辅助类
|
||
├── EFileVerifyLevel.cs # 文件校验等级枚举
|
||
├── EFileVerifyResult.cs # 文件校验结果枚举
|
||
└── EFileClearMode.cs # 文件清理模式枚举
|
||
```
|
||
|
||
---
|
||
|
||
## 核心接口
|
||
|
||
### IFileSystem（文件系统接口）
|
||
|
||
定义文件系统的核心契约，所有文件系统实现都必须实现此接口。
|
||
|
||
```csharp
|
||
internal interface IFileSystem
|
||
{
|
||
// 基本属性
|
||
string PackageName { get; } // 包裹名称
|
||
string FileRoot { get; } // 文件根目录
|
||
int FileCount { get; } // 文件数量
|
||
|
||
// 生命周期
|
||
void OnCreate(string packageName, string packageRoot);
|
||
void OnDestroy();
|
||
void SetParameter(string name, object value);
|
||
|
||
// 异步操作
|
||
FSInitializeFileSystemOperation InitializeFileSystemAsync();
|
||
FSRequestPackageVersionOperation RequestPackageVersionAsync(bool appendTimeTicks, int timeout);
|
||
FSLoadPackageManifestOperation LoadPackageManifestAsync(string packageVersion, int timeout);
|
||
FSLoadBundleOperation LoadBundleFile(PackageBundle bundle);
|
||
FSDownloadFileOperation DownloadFileAsync(PackageBundle bundle, DownloadFileOptions options);
|
||
FSClearCacheFilesOperation ClearCacheFilesAsync(PackageManifest manifest, ClearCacheFilesOptions options);
|
||
|
||
// 文件查询
|
||
bool Belong(PackageBundle bundle); // 查询文件归属
|
||
bool Exists(PackageBundle bundle); // 查询文件是否存在
|
||
bool NeedDownload(PackageBundle bundle);// 是否需要下载
|
||
bool NeedUnpack(PackageBundle bundle); // 是否需要解压
|
||
bool NeedImport(PackageBundle bundle); // 是否需要导入
|
||
|
||
// 文件访问
|
||
string GetBundleFilePath(PackageBundle bundle);
|
||
byte[] ReadBundleFileData(PackageBundle bundle);
|
||
string ReadBundleFileText(PackageBundle bundle);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 操作类定义
|
||
|
||
### 文件系统操作基类
|
||
|
||
所有文件系统操作都继承自 `AsyncOperationBase`，提供异步执行能力。
|
||
|
||
| 操作类 | 说明 | 输出属性 |
|
||
|--------|------|----------|
|
||
| `FSInitializeFileSystemOperation` | 初始化文件系统 | - |
|
||
| `FSRequestPackageVersionOperation` | 请求包裹版本 | `PackageVersion` |
|
||
| `FSLoadPackageManifestOperation` | 加载资源清单 | `Manifest` |
|
||
| `FSLoadBundleOperation` | 加载资源包文件 | `Result`, `DownloadProgress`, `DownloadedBytes` |
|
||
| `FSDownloadFileOperation` | 下载文件 | `DownloadedBytes`, `DownloadProgress` |
|
||
| `FSClearCacheFilesOperation` | 清理缓存文件 | - |
|
||
|
||
### 资源加载操作基类
|
||
|
||
| 操作类 | 说明 | 输出属性 |
|
||
|--------|------|----------|
|
||
| `FSLoadAssetOperation` | 加载单个资源 | `Result` (Object) |
|
||
| `FSLoadAllAssetsOperation` | 加载所有资源 | `Result` (Object[]) |
|
||
| `FSLoadSubAssetsOperation` | 加载子资源 | `Result` (Object[]) |
|
||
| `FSLoadSceneOperation` | 加载场景 | `Result` (Scene) |
|
||
|
||
---
|
||
|
||
## BundleResult 资源包结果
|
||
|
||
### 基类定义
|
||
|
||
```csharp
|
||
internal abstract class BundleResult
|
||
{
|
||
// 资源包管理
|
||
public abstract void UnloadBundleFile();
|
||
public abstract string GetBundleFilePath();
|
||
public abstract byte[] ReadBundleFileData();
|
||
public abstract string ReadBundleFileText();
|
||
|
||
// 资源加载
|
||
public abstract FSLoadAssetOperation LoadAssetAsync(AssetInfo assetInfo);
|
||
public abstract FSLoadAllAssetsOperation LoadAllAssetsAsync(AssetInfo assetInfo);
|
||
public abstract FSLoadSubAssetsOperation LoadSubAssetsAsync(AssetInfo assetInfo);
|
||
public abstract FSLoadSceneOperation LoadSceneOperation(AssetInfo assetInfo, LoadSceneParameters loadParams, bool suspendLoad);
|
||
}
|
||
```
|
||
|
||
### 实现类型
|
||
|
||
| 类型 | 说明 | 使用场景 |
|
||
|------|------|----------|
|
||
| `AssetBundleResult` | Unity AssetBundle 结果 | 正常构建的 AssetBundle 文件 |
|
||
| `RawBundleResult` | 原生文件结果 | 原生文件（非 AssetBundle） |
|
||
| `VirtualBundleResult` | 虚拟资源包结果 | 编辑器模拟模式 |
|
||
|
||
---
|
||
|
||
## 枚举定义
|
||
|
||
### EFileVerifyLevel（文件校验等级）
|
||
|
||
```csharp
|
||
public enum EFileVerifyLevel
|
||
{
|
||
Low = 1, // 仅验证文件存在
|
||
Middle = 2, // 验证文件大小
|
||
High = 3 // 验证文件大小和 CRC
|
||
}
|
||
```
|
||
|
||
### EFileVerifyResult（文件校验结果）
|
||
|
||
```csharp
|
||
internal enum EFileVerifyResult
|
||
{
|
||
Exception = -7, // 验证异常
|
||
CacheNotFound = -6, // 未找到缓存信息
|
||
InfoFileNotExisted = -5, // 信息文件不存在
|
||
DataFileNotExisted = -4, // 数据文件不存在
|
||
FileNotComplete = -3, // 文件内容不足
|
||
FileOverflow = -2, // 文件内容溢出
|
||
FileCrcError = -1, // 文件 CRC 不匹配
|
||
None = 0, // 默认状态
|
||
Succeed = 1 // 验证成功
|
||
}
|
||
```
|
||
|
||
### EFileClearMode（文件清理模式）
|
||
|
||
```csharp
|
||
public enum EFileClearMode
|
||
{
|
||
ClearAllBundleFiles, // 清理所有资源文件
|
||
ClearUnusedBundleFiles, // 清理未使用的资源文件
|
||
ClearBundleFilesByLocations,// 按地址清理资源文件
|
||
ClearBundleFilesByTags, // 按标签清理资源文件
|
||
ClearAllManifestFiles, // 清理所有清单文件
|
||
ClearUnusedManifestFiles // 清理未使用的清单文件
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 参数系统
|
||
|
||
### FileSystemParameters（文件系统参数）
|
||
|
||
用于创建和配置文件系统实例。
|
||
|
||
```csharp
|
||
public class FileSystemParameters
|
||
{
|
||
public string FileSystemClass { get; } // 文件系统类名
|
||
public string PackageRoot { get; } // 包裹根目录
|
||
|
||
public void AddParameter(string name, object value);
|
||
}
|
||
```
|
||
|
||
### 参数名称常量
|
||
|
||
```csharp
|
||
public class FileSystemParametersDefine
|
||
{
|
||
// 文件校验
|
||
public const string FILE_VERIFY_LEVEL = "FILE_VERIFY_LEVEL";
|
||
public const string FILE_VERIFY_MAX_CONCURRENCY = "FILE_VERIFY_MAX_CONCURRENCY";
|
||
|
||
// 下载配置
|
||
public const string DOWNLOAD_MAX_CONCURRENCY = "DOWNLOAD_MAX_CONCURRENCY";
|
||
public const string DOWNLOAD_MAX_REQUEST_PER_FRAME = "DOWNLOAD_MAX_REQUEST_PER_FRAME";
|
||
public const string DOWNLOAD_WATCH_DOG_TIME = "DOWNLOAD_WATCH_DOG_TIME";
|
||
public const string RESUME_DOWNLOAD_MINMUM_SIZE = "RESUME_DOWNLOAD_MINMUM_SIZE";
|
||
public const string RESUME_DOWNLOAD_RESPONSE_CODES = "RESUME_DOWNLOAD_RESPONSE_CODES";
|
||
|
||
// 服务接口
|
||
public const string REMOTE_SERVICES = "REMOTE_SERVICES";
|
||
public const string DECRYPTION_SERVICES = "DECRYPTION_SERVICES";
|
||
public const string MANIFEST_SERVICES = "MANIFEST_SERVICES";
|
||
public const string COPY_LOCAL_FILE_SERVICES = "COPY_LOCAL_FILE_SERVICES";
|
||
|
||
// 功能开关
|
||
public const string DISABLE_CATALOG_FILE = "DISABLE_CATALOG_FILE";
|
||
public const string DISABLE_UNITY_WEB_CACHE = "DISABLE_UNITY_WEB_CACHE";
|
||
public const string DISABLE_ONDEMAND_DOWNLOAD = "DISABLE_ONDEMAND_DOWNLOAD";
|
||
public const string APPEND_FILE_EXTENSION = "APPEND_FILE_EXTENSION";
|
||
|
||
// 模拟模式
|
||
public const string VIRTUAL_WEBGL_MODE = "VIRTUAL_WEBGL_MODE";
|
||
public const string VIRTUAL_DOWNLOAD_MODE = "VIRTUAL_DOWNLOAD_MODE";
|
||
public const string VIRTUAL_DOWNLOAD_SPEED = "VIRTUAL_DOWNLOAD_SPEED";
|
||
public const string ASYNC_SIMULATE_MIN_FRAME = "ASYNC_SIMULATE_MIN_FRAME";
|
||
public const string ASYNC_SIMULATE_MAX_FRAME = "ASYNC_SIMULATE_MAX_FRAME";
|
||
|
||
// 其他
|
||
public const string INSTALL_CLEAR_MODE = "INSTALL_CLEAR_MODE";
|
||
public const string COPY_BUILDIN_PACKAGE_MANIFEST = "COPY_BUILDIN_PACKAGE_MANIFEST";
|
||
public const string UNPACK_FILE_SYSTEM_ROOT = "UNPACK_FILE_SYSTEM_ROOT";
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 创建文件系统参数
|
||
|
||
```csharp
|
||
// 编辑器文件系统
|
||
var editorParams = FileSystemParameters.CreateDefaultEditorFileSystemParameters(
|
||
packageRoot: "Assets/GameRes/Bundles"
|
||
);
|
||
|
||
// 内置文件系统
|
||
var buildinParams = FileSystemParameters.CreateDefaultBuildinFileSystemParameters(
|
||
decryptionServices: new MyDecryptionServices()
|
||
);
|
||
|
||
// 缓存文件系统
|
||
var cacheParams = FileSystemParameters.CreateDefaultCacheFileSystemParameters(
|
||
remoteServices: new MyRemoteServices(),
|
||
decryptionServices: new MyDecryptionServices()
|
||
);
|
||
|
||
// WebGL 服务器文件系统
|
||
var webServerParams = FileSystemParameters.CreateDefaultWebServerFileSystemParameters(
|
||
disableUnityWebCache: true
|
||
);
|
||
|
||
// WebGL 远程文件系统
|
||
var webRemoteParams = FileSystemParameters.CreateDefaultWebRemoteFileSystemParameters(
|
||
remoteServices: new MyRemoteServices(),
|
||
disableUnityWebCache: true
|
||
);
|
||
```
|
||
|
||
### 添加自定义参数
|
||
|
||
```csharp
|
||
var cacheParams = FileSystemParameters.CreateDefaultCacheFileSystemParameters(remoteServices);
|
||
|
||
// 设置文件校验级别
|
||
cacheParams.AddParameter(FileSystemParametersDefine.FILE_VERIFY_LEVEL, EFileVerifyLevel.High);
|
||
|
||
// 设置下载并发数
|
||
cacheParams.AddParameter(FileSystemParametersDefine.DOWNLOAD_MAX_CONCURRENCY, 16);
|
||
|
||
// 设置看门狗时间
|
||
cacheParams.AddParameter(FileSystemParametersDefine.DOWNLOAD_WATCH_DOG_TIME, 30);
|
||
```
|
||
|
||
---
|
||
|
||
## 文件系统实现
|
||
|
||
| 文件系统 | 说明 | 适用场景 |
|
||
|----------|------|----------|
|
||
| `DefaultEditorFileSystem` | 编辑器模拟文件系统 | 编辑器开发，快速迭代 |
|
||
| `DefaultBuildinFileSystem` | 内置资源文件系统 | StreamingAssets 内置资源 |
|
||
| `DefaultCacheFileSystem` | 缓存资源文件系统 | 下载并缓存的远程资源 |
|
||
| `DefaultUnpackFileSystem` | 解压资源文件系统 | 从内置解压到沙盒的资源 |
|
||
| `DefaultWebServerFileSystem` | WebGL 服务器文件系统 | WebGL 本地服务器资源 |
|
||
| `DefaultWebRemoteFileSystem` | WebGL 远程文件系统 | WebGL 远程 CDN 资源 |
|
||
|
||
---
|
||
|
||
## 设计模式
|
||
|
||
### 策略模式
|
||
|
||
通过 `IFileSystem` 接口实现可插拔的文件系统：
|
||
|
||
```
|
||
IFileSystem (接口)
|
||
│
|
||
├── DefaultEditorFileSystem
|
||
├── DefaultBuildinFileSystem
|
||
├── DefaultCacheFileSystem
|
||
│ └── DefaultUnpackFileSystem (继承)
|
||
├── DefaultWebServerFileSystem
|
||
└── DefaultWebRemoteFileSystem
|
||
```
|
||
|
||
### 工厂模式
|
||
|
||
`FileSystemParameters` 通过反射创建文件系统实例：
|
||
|
||
```csharp
|
||
internal IFileSystem CreateFileSystem(string packageName)
|
||
{
|
||
Type classType = Type.GetType(FileSystemClass);
|
||
var instance = (IFileSystem)Activator.CreateInstance(classType, true);
|
||
|
||
foreach (var param in CreateParameters)
|
||
instance.SetParameter(param.Key, param.Value);
|
||
|
||
instance.OnCreate(packageName, PackageRoot);
|
||
return instance;
|
||
}
|
||
```
|
||
|
||
### 模板方法模式
|
||
|
||
`BundleResult` 定义资源加载的算法骨架，子类实现具体加载逻辑：
|
||
|
||
```
|
||
BundleResult (抽象基类)
|
||
│
|
||
├── AssetBundleResult → AssetBundle.LoadAssetAsync
|
||
├── RawBundleResult → 直接读取文件
|
||
└── VirtualBundleResult → AssetDatabase.LoadAssetAtPath
|
||
```
|
||
|
||
---
|
||
|
||
## 类继承关系
|
||
|
||
```
|
||
AsyncOperationBase
|
||
│
|
||
├── FSInitializeFileSystemOperation
|
||
├── FSRequestPackageVersionOperation
|
||
├── FSLoadPackageManifestOperation
|
||
├── FSLoadBundleOperation
|
||
│ └── FSLoadBundleCompleteOperation
|
||
├── FSDownloadFileOperation
|
||
├── FSClearCacheFilesOperation
|
||
│ └── FSClearCacheFilesCompleteOperation
|
||
├── FSLoadAssetOperation
|
||
├── FSLoadAllAssetsOperation
|
||
├── FSLoadSubAssetsOperation
|
||
└── FSLoadSceneOperation
|
||
|
||
BundleResult
|
||
│
|
||
├── AssetBundleResult
|
||
├── RawBundleResult
|
||
└── VirtualBundleResult
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **文件系统选择**：根据运行模式选择合适的文件系统组合
|
||
2. **参数配置**：合理配置校验等级和并发数，平衡性能和安全性
|
||
3. **自定义扩展**：可通过实现 `IFileSystem` 接口创建自定义文件系统
|
||
4. **WebGL 限制**：WebGL 平台不支持持久化缓存，需使用专用文件系统
|
||
5. **解密服务**：加密资源需要提供对应的解密服务实现
|