游戏客户端架构 / 系统课时
为存档接口设计统一抽象层
为存档接口设计统一抽象层
这节把“文件、云端、引擎目录、测试内存”统一收进一个边界。目标不是发明万能接口,而是让业务层只关心保存、读取、删除和列举,让迁移规则独立演进,底层再按 Unity、Godot、本地文件或 Steam 选择适配器。
学习目标
- 定义足够小且稳定的存档存储接口
- 将格式迁移与物理存储解耦,避免适配器理解业务结构
- 用内存实现验证接口是否易测试、易替换
先把存储能力压到最小集合
统一抽象层最重要的是不要泄漏底层细节。业务层不应该知道 Steam 路径、Unity 的持久化目录或某个文件扩展名,只需要一个稳定的 slotId 和字节数据。
保存、读取、删除、列举属于物理存储职责;迁移属于数据格式职责。把两者分成 ISaveStore 与 ISaveMigrator,可以避免未来增加云端实现时复制一套迁移代码。

用一个可运行示例检验接口边界
下面用 C# 定义最小接口,并用内存实现验证调用方不需要知道底层存储位置。真实项目里可以把 InMemorySaveStore 换成文件、Steam Remote Storage 或其他平台适配器,而上层调用方式保持不变。
using System.Text;
public record SavePayload(byte[] Data, int SchemaVersion);
public record SaveInfo(string SlotId, int SchemaVersion, int SizeBytes);
public interface ISaveStore
{
Task SaveAsync(string slotId, SavePayload payload, CancellationToken ct = default);
Task<SavePayload?> LoadAsync(string slotId, CancellationToken ct = default);
Task<bool> DeleteAsync(string slotId, CancellationToken ct = default);
Task<IReadOnlyList<SaveInfo>> ListAsync(CancellationToken ct = default);
}
public interface ISaveMigrator
{
ValueTask<SavePayload> MigrateAsync(
SavePayload payload,
int targetSchemaVersion,
CancellationToken ct = default);
}
public sealed class InMemorySaveStore : ISaveStore
{
private readonly Dictionary<string, SavePayload> _items = new();
public Task SaveAsync(string slotId, SavePayload payload, CancellationToken ct = default)
{
ct.ThrowIfCancellationRequested();
_items[slotId] = payload;
return Task.CompletedTask;
}
public Task<SavePayload?> LoadAsync(string slotId, CancellationToken ct = default)
{
ct.ThrowIfCancellationRequested();
_items.TryGetValue(slotId, out var payload);
return Task.FromResult(payload);
}
public Task<bool> DeleteAsync(string slotId, CancellationToken ct = default)
{
ct.ThrowIfCancellationRequested();
return Task.FromResult(_items.Remove(slotId));
}
public Task<IReadOnlyList<SaveInfo>> ListAsync(CancellationToken ct = default)
{
ct.ThrowIfCancellationRequested();
IReadOnlyList<SaveInfo> result = _items
.OrderBy(x => x.Key)
.Select(x => new SaveInfo(x.Key, x.Value.SchemaVersion, x.Value.Data.Length))
.ToList();
return Task.FromResult(result);
}
}
public static class Program
{
public static async Task Main()
{
ISaveStore store = new InMemorySaveStore();
var payload = new SavePayload(Encoding.UTF8.GetBytes("hello"), 3);
await store.SaveAsync("slot-01", payload);
var list = await store.ListAsync();
Console.WriteLine($"slots={list.Count}");
Console.WriteLine($"{list[0].SlotId}:v{list[0].SchemaVersion}:{list[0].SizeBytes}bytes");
var loaded = await store.LoadAsync("slot-01");
Console.WriteLine($"loaded=v{loaded!.SchemaVersion},bytes={loaded.Data.Length}");
var deleted = await store.DeleteAsync("slot-01");
Console.WriteLine($"deleted={deleted}");
Console.WriteLine($"slots={(await store.ListAsync()).Count}");
}
}预期输出:
slots=1
slot-01:v3:5bytes
loaded=v3,bytes=5
deleted=True
slots=0这个示例故意不提供路径参数,因为路径属于适配器配置,而不是领域调用参数。CancellationToken 保留在异步边界上,使文件 I/O、网络 I/O 和测试替身都能使用同一套取消语义。
让迁移发生在读取之后、交付之前
读取旧存档时,存储层只负责返回字节和 SchemaVersion。上层发现版本低于当前版本后,再调用 ISaveMigrator 逐级升级,验证成功后把新版本重新保存。这样本地文件适配器和 Steam 适配器都不需要理解“版本 2 到版本 3 增加了哪些字段”。
建议把迁移做成单向、可重复测试的转换链,例如 v1 -> v2 -> v3,而不是要求每个旧版本直接跳到最新版。迁移失败时保留原始数据,不要先覆盖旧文件再尝试转换。
为不同引擎实现适配器
Unity、Godot 或自研引擎的差异主要集中在路径解析、文件 API、线程模型和平台服务接入。把这些差异限制在适配器内部后,核心存档服务只依赖 ISaveStore,引擎启动时负责选择具体实现并注入。
文件实现应保证临时文件写入、校验、原子替换等持久化语义;Steam 实现负责平台 API 与同步错误映射;测试实现可以像上面的内存版本一样完全不触碰磁盘。这样同一组保存、读取和删除测试就能复用于所有适配器的契约测试。
检查抽象是否过度
一个好接口应让调用方容易使用,也让实现方容易遵守。如果你发现方法参数不断出现 steamAppId、绝对路径、Unity 对象或某个平台错误码,说明底层细节已经穿透边界;如果接口为了“未来可能用到”塞进二十多个方法,也说明抽象过度。
最终可以用一个简单标准判断:把 InMemorySaveStore 换成 LocalFileSaveStore 时,业务层代码是否完全不用改;把存档格式从 v3 升到 v4 时,存储适配器是否完全不用改。两个答案都为“是”,这套抽象层才真正具备可测试、可替换和可演进的价值。