docs : 增加模块的文档说明

This commit is contained in:
何冠峰
2026-01-06 17:12:07 +08:00
parent 539ca3523e
commit 454afc9ba6
24 changed files with 8254 additions and 0 deletions
@@ -0,0 +1,464 @@
# 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. **解密服务**:加密资源需要提供对应的解密服务实现