100 lines
2.6 KiB
Markdown
100 lines
2.6 KiB
Markdown
# P0-5: IConfigProvider 需求详细文档
|
||
|
||
## 对齐说明
|
||
|
||
本文档以 `docs/requirements/p0-requirements-set.md` 为准。P0 配置系统只交付 JSON 强类型读取；CSV、Luban、ScriptableObject、远程配置、热重载和模块化加载全部放到 P1/P2 插件化扩展。
|
||
|
||
## 目标
|
||
|
||
提供最小可用的 JSON 配置加载和查询接口，支撑 P0 Sample 和休闲游戏基础配置读取。
|
||
|
||
## 接口
|
||
|
||
```csharp
|
||
public interface IConfigProvider
|
||
{
|
||
Task LoadAllAsync(CancellationToken cancellationToken);
|
||
T Get<T>(int id) where T : class, IConfigRow;
|
||
IReadOnlyList<T> GetAll<T>() where T : class, IConfigRow;
|
||
}
|
||
|
||
public interface IConfigRow
|
||
{
|
||
int Id { get; }
|
||
}
|
||
```
|
||
|
||
## 功能需求
|
||
|
||
- 启动时通过 `LoadAllAsync` 加载全部 JSON 配置。
|
||
- 配置行必须实现 `IConfigRow`。
|
||
- 查询使用泛型类型 + `Id`。
|
||
- `Get<T>(missingId)` 返回 null。
|
||
- `GetAll<T>()` 返回只读列表；未加载该类型时返回空列表。
|
||
- 同一配置类型内重复 Id 必须抛异常。
|
||
- JSON 格式错误必须抛异常并包含文件名。
|
||
|
||
## 配置文件约定
|
||
|
||
P0 默认采用约定路径，具体路径可由实现固定，例如：
|
||
|
||
```text
|
||
Assets/Configs/
|
||
├── weapons.json
|
||
├── levels.json
|
||
└── settings.json
|
||
```
|
||
|
||
每个 JSON 文件对应一种配置行类型。类型和文件的映射可以在 GameBootstrap 中显式注册，P0 不要求目录扫描和自动类型发现。
|
||
|
||
## 暂不做
|
||
|
||
- 字符串模块名查询。
|
||
- 混合查询模式。
|
||
- CSV。
|
||
- Luban。
|
||
- ScriptableObject 配置。
|
||
- 按模块加载/卸载。
|
||
- 远程配置。
|
||
- 热重载。
|
||
- 字段范围校验和引用完整性校验。
|
||
- 配置编辑器工具。
|
||
|
||
## 扩展方向
|
||
|
||
P1/P2 通过以下接口扩展，不修改业务调用：
|
||
|
||
```csharp
|
||
public interface IConfigParser
|
||
{
|
||
string Format { get; }
|
||
IReadOnlyList<T> Parse<T>(string content) where T : class, IConfigRow;
|
||
}
|
||
|
||
public interface IConfigSource
|
||
{
|
||
Task<string> LoadTextAsync(string key, CancellationToken cancellationToken);
|
||
}
|
||
```
|
||
|
||
## 验收标准
|
||
|
||
| # | 标准 | 通过条件 |
|
||
|---|------|---------|
|
||
| 1 | JSON 加载 | `LoadAllAsync` 后配置可查询 |
|
||
| 2 | 按 Id 查询 | `Get<WeaponConfig>(101)` 返回正确对象 |
|
||
| 3 | 不存在 Id | 返回 null，不抛异常 |
|
||
| 4 | 获取列表 | `GetAll<WeaponConfig>()` 返回全部配置 |
|
||
| 5 | 重复 Id | 加载时抛异常并包含重复 Id |
|
||
| 6 | 格式错误 | 抛异常并包含文件名 |
|
||
| 7 | 取消加载 | CancellationToken 取消时抛 `OperationCanceledException` |
|
||
|
||
## 依赖关系
|
||
|
||
```text
|
||
IConfigProvider
|
||
├── JSON 库
|
||
├── 可选 IResourceService 或文件读取适配
|
||
└── 纯 C# 配置行类型
|
||
```
|