游戏客户端架构 / 系统课时

为存档接口设计统一抽象层

为存档接口设计统一抽象层

这节把“文件、云端、引擎目录、测试内存”统一收进一个边界。目标不是发明万能接口,而是让业务层只关心保存、读取、删除和列举,让迁移规则独立演进,底层再按 Unity、Godot、本地文件或 Steam 选择适配器。

学习目标

  • 定义足够小且稳定的存档存储接口
  • 将格式迁移与物理存储解耦,避免适配器理解业务结构
  • 用内存实现验证接口是否易测试、易替换

先把存储能力压到最小集合

统一抽象层最重要的是不要泄漏底层细节。业务层不应该知道 Steam 路径、Unity 的持久化目录或某个文件扩展名,只需要一个稳定的 slotId 和字节数据。

保存、读取、删除、列举属于物理存储职责;迁移属于数据格式职责。把两者分成 ISaveStore 与 ISaveMigrator,可以避免未来增加云端实现时复制一套迁移代码。

统一存档抽象层与不同适配器的结构关系

用一个可运行示例检验接口边界

下面用 C# 定义最小接口,并用内存实现验证调用方不需要知道底层存储位置。真实项目里可以把 InMemorySaveStore 换成文件、Steam Remote Storage 或其他平台适配器,而上层调用方式保持不变。

csharp
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}");
    }
}

预期输出:

text
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 时,存储适配器是否完全不用改。两个答案都为“是”,这套抽象层才真正具备可测试、可替换和可演进的价值。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

为存档接口设计统一抽象层

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通