第2章 缓存数据结构设计：对象模型、序列化方式、版本兼容性

离线缓存方案的核心竞争力在于其数据结构设计的健壮性与演进能力。本章围绕三个关键维度展开：对象模型定义缓存实体的边界与关系；序列化方式决定数据的存储效率与跨语言互通能力；版本兼容性确保缓存数据在SDK升级过程中不失效、不崩溃。三者共同构成缓存数据层的基石。

2.1 缓存对象模型

缓存对象模型采用分层结构，将数据、元数据、索引和版本控制分离，降低耦合度，提升扩展性。核心实体包括以下五类：

2.2 序列化方式对比与选型

序列化方式直接影响缓存写入/读取性能、存储空间占用以及版本演进的灵活性。以下对三种主流方案进行对比：

2.3 版本兼容性策略

版本兼容性通过 字段编号锁定 和 SchemaVersion 注册表 实现。核心规则如下：

1. 向前兼容（Forward Compat）：新版本SDK可以读取旧版本写入的缓存数据——只允许追加字段，不得删除或修改已有字段编号。
2. 向后兼容（Backward Compat）：旧版本SDK可以读取新版本写入的缓存数据——新版本中废弃的字段需保留默认值占位，并通过 deprecatedVersion 标记。
3. 破坏性变更隔离：当必须删除或重命名字段时，将 SchemaVersion.major 递增，并清空所有受影响的缓存分区。

Protocol Buffers 中通过 field number 和 reserved 关键字实现锁定：

// cache_entry.proto (v1)
syntax = "proto3";
package cache;

message CacheEntry {
  string key = 1;
  bytes value = 2;
  int64 created_at = 3;
  int64 ttl = 4;
  int32 schema_version = 5;
  
  // 预留给未来扩展 (1~15 占1字节, 16~2047 占2字节)
  reserved 6 to 10;
}

// cache_entry.proto (v2) — 向前兼容追加字段
message CacheEntry {
  string key = 1;
  bytes value = 2;
  int64 created_at = 3;
  int64 ttl = 4;
  int32 schema_version = 5;
  string etag = 6;               // 新增字段，编号6
  map<string,string> tags = 7;   // 新增字段，编号7
  reserved 8 to 10;
}

2.4 实现流程：序列化与版本兼容处理

以下实现序列化器，支持多版本反序列化与自动降级：

// CacheSerializer.java
public class CacheSerializer {
    private static final int LATEST_SCHEMA_VERSION = 2;
    private final Map<Integer, ProtoDeserializer<?>> deserializerMap = new HashMap<>();

    public CacheSerializer() {
        // 注册每个版本的 deserializer
        deserializerMap.put(1, new V1Deserializer());
        deserializerMap.put(2, new V2Deserializer());
    }

    public byte[] serialize(CacheEntry entry) {
        CacheEntryProto.CacheEntry.Builder builder = CacheEntryProto.CacheEntry.newBuilder()
                .setKey(entry.getKey())
                .setValue(ByteString.copyFrom(entry.getValue()))
                .setCreatedAt(entry.getCreatedAt())
                .setTtl(entry.getTtl())
                .setSchemaVersion(LATEST_SCHEMA_VERSION);
        if (entry.getEtag() != null) {
            builder.setEtag(entry.getEtag());
        }
        return builder.build().toByteArray();
    }

    public CacheEntry deserialize(byte[] data, int storedVersion) {
        // 获取对应版本的 deserializer，若不存在则向上兼容
        ProtoDeserializer<?> deserializer = deserializerMap.get(storedVersion);
        if (deserializer == null) {
            // 尝试找最近的低版本 deserializer
            Integer fallback = findNearestCompatible(storedVersion);
            if (fallback == null) {
                throw new IncompatibleCacheVersionException("No deserializer for v" + storedVersion);
            }
            deserializer = deserializerMap.get(fallback);
            Log.w("CacheSerializer", "Falling back from v" + storedVersion + " to v" + fallback);
        }
        return deserializer.deserialize(data);
    }

    private Integer findNearestCompatible(int version) {
        for (int v = version - 1; v >= 1; v--) {
            if (deserializerMap.containsKey(v)) return v;
        }
        return null;
    }
}

2.5 调试与日志：版本兼容性检查

在缓存加载时加入版本校验日志，快速定位数据损坏或版本不匹配问题：

// 调试日志示例：加载缓存时的版本检查
public CacheEntry loadFromDisk(String key) {
    byte[] raw = storage.read(key);
    if (raw == null || raw.length < 4) {
        Log.w("CacheLoader", "Corrupt data for key=" + key + ", length=" + (raw == null ? -1 : raw.length));
        return null;
    }
    int storedVersion = extractVersion(raw);
    int currentVersion = CacheSerializer.LATEST_SCHEMA_VERSION;
    if (storedVersion > currentVersion) {
        Log.e("CacheLoader", "Future version detected: stored=" + storedVersion
                + ", current=" + currentVersion + ". Try fallback deserializer.");
    } else if (storedVersion < currentVersion - 1) {
        Log.i("CacheLoader", "Legacy data v" + storedVersion + ", upgrading on read.");
    }
    return serializer.deserialize(raw, storedVersion);
}

2.6 部署配置：序列化方式切换

在应用启动时通过配置选择序列化后端，便于灰度切换或 A/B 测试：

// CacheConfig.java
public class CacheConfig {
    public enum SerializerBackend { JSON, PROTOBUF, FLATBUFFERS }

    private SerializerBackend backend = SerializerBackend.PROTOBUF;

    public void setSerializerBackend(SerializerBackend backend) {
        this.backend = backend;
        Log.i("CacheConfig", "Serializer switched to " + backend);
        // 切换后需清空旧序列化格式的缓存分区，防止数据错乱
        CacheManager.getInstance().invalidatePartition("default");
    }

    public ISerializer createSerializer() {
        switch (backend) {
            case JSON:       return new JsonCacheSerializer();
            case PROTOBUF:   return new ProtoCacheSerializer();
            case FLATBUFFERS: return new FlatBuffersCacheSerializer();
            default:         return new ProtoCacheSerializer();
        }
    }
}

2.7 性能对比数据（基于 Android 12 / Pixel 6）

2.8 常见错误与修复