105 lines
2.7 KiB
Markdown
105 lines
2.7 KiB
Markdown
# P0-7: IResourceService 需求详细文档
|
||
|
||
## 对齐说明
|
||
|
||
本文档以 `docs/requirements/p0-requirements-set.md` 为准。P0 资源系统包含引用计数和资源组，因为它直接影响 Feature 释放正确性；但 P0 只实现 Addressables 默认后端，其他后端通过插件扩展。
|
||
|
||
## 目标
|
||
|
||
提供异步资源加载、同 key 并发合并、引用计数和资源组释放能力。
|
||
|
||
## 接口
|
||
|
||
```csharp
|
||
public interface IResourceService
|
||
{
|
||
Task<IResourceHandle<T>> LoadAsync<T>(
|
||
string key,
|
||
CancellationToken cancellationToken)
|
||
where T : class;
|
||
|
||
IResourceGroup CreateGroup();
|
||
}
|
||
|
||
public interface IResourceHandle<T> : IDisposable where T : class
|
||
{
|
||
string Key { get; }
|
||
T Asset { get; }
|
||
bool IsDisposed { get; }
|
||
}
|
||
|
||
public interface IResourceGroup : IDisposable
|
||
{
|
||
void Add<T>(IResourceHandle<T> handle) where T : class;
|
||
int Count { get; }
|
||
}
|
||
```
|
||
|
||
## 行为规则
|
||
|
||
- `LoadAsync<T>` 加载失败时抛异常，异常包含 key 和后端类型。
|
||
- 同 key 同类型并发加载只触发一次底层加载。
|
||
- 每次 `LoadAsync` 返回独立 handle。
|
||
- 每个 handle Dispose 时引用计数减一。
|
||
- 最后一个 handle Dispose 时释放底层资源。
|
||
- `IResourceGroup.Dispose` 释放组内所有 handle。
|
||
- 重复 Dispose 不抛异常。
|
||
- Group 重复 Add 同一个 handle 时忽略。
|
||
- Dispose 后访问 `Asset` 的行为必须固定为返回 null。
|
||
|
||
## 默认后端
|
||
|
||
P0 默认只支持 Addressables。
|
||
|
||
```text
|
||
IResourceService
|
||
└── AddressablesResourceBackend
|
||
```
|
||
|
||
## 暂不做
|
||
|
||
- Resources 后端。
|
||
- AssetBundle 后端。
|
||
- YooAsset 后端。
|
||
- 资源预热。
|
||
- 下载进度回调。
|
||
- 资源优先级。
|
||
- 资源版本管理。
|
||
- 编辑器资源扫描和分析工具。
|
||
|
||
## 扩展方向
|
||
|
||
P1/P2 通过后端接口扩展：
|
||
|
||
```csharp
|
||
public interface IResourceBackend
|
||
{
|
||
Task<T> LoadAsync<T>(string key, CancellationToken cancellationToken)
|
||
where T : class;
|
||
|
||
void Release(string key, object asset);
|
||
}
|
||
```
|
||
|
||
## 验收标准
|
||
|
||
| # | 标准 | 通过条件 |
|
||
|---|------|---------|
|
||
| 1 | 正常加载 | LoadAsync 返回 handle，Asset 可用 |
|
||
| 2 | 加载失败 | 不存在 key 抛异常并包含 key |
|
||
| 3 | 引用计数 | 同 key 加载两次，最后一个 handle Dispose 后才释放底层资源 |
|
||
| 4 | 并发合并 | 同 key 并发 LoadAsync 只触发一次底层加载 |
|
||
| 5 | Group 释放 | Group Dispose 后组内 handle 全部释放 |
|
||
| 6 | 重复 Dispose | handle/group 重复 Dispose 不抛异常 |
|
||
| 7 | Dispose 后 Asset | 返回 null |
|
||
| 8 | 取消加载 | CancellationToken 取消时抛 `OperationCanceledException` |
|
||
|
||
## 依赖关系
|
||
|
||
```text
|
||
IResourceService
|
||
├── Addressables
|
||
├── CancellationToken
|
||
└── 被 Feature / UIManager / AudioService 依赖
|
||
```
|