4、数据格式兼容性：不同版本SDK数据格式不统一，如何设计兼容方案？

数据格式不统一，这问题我太熟了。早期做SDK的时候，版本迭代一快，前后端数据字段说变就变。客户端升级慢，服务端又急着推新版本，两边数据对不上，埋点全乱套。

说白了，这就是个向前兼容的问题。新版本SDK要能读懂老版本的数据，老版本SDK也不能因为收到新格式就崩溃。今天我就把压箱底的兼容方案拆开来讲。

4.1 问题的根源：版本裂谷

为什么会格式不统一？我归纳了三个典型场景：

• 字段增减：新版本加了“页面停留时长”，老版本没有这个字段。
• 类型变更：老版本“价格”是字符串"99.00"，新版本改成数字99.00。
• 结构重组：老版本是扁平对象，新版本改成嵌套结构。

你想想看，如果App里同时跑着SDK v2.3和v3.1，服务端收到的数据格式五花八门，解析逻辑写起来简直要命。

4.2 核心兼容策略：版本号+适配器

我的做法很简单——每条数据都带版本号。服务端根据版本号选择对应的解析器。这就像快递单上写清楚“这是哪个仓库发的货”，仓库不同，分拣规则自然不同。

来看一个实际的数据结构设计：

// 统一数据信封
{
  "version": "3.1.0",        // SDK版本号
  "event": "page_view",
  "timestamp": 1712563200000,
  "payload": {               // 实际业务数据
    "page_id": "home",
    "duration": 120
  }
}

服务端拿到数据后，先读version字段，再路由到对应的解析器。这样新老版本的数据就能和平共处了。

4.3 适配器模式：让不同版本的数据“说同一种语言”

我个人习惯用适配器模式来处理版本差异。每个版本写一个适配器，负责把该版本的数据转换成统一的内部格式。

举个例子：

// 适配器接口
interface DataAdapter {
  boolean supports(String version);
  UnifiedData adapt(Map<String, Object> rawData);
}

// v2.3 适配器
class V2_3Adapter implements DataAdapter {
  @Override
  public boolean supports(String version) {
    return version.startsWith("2.3");
  }

  @Override
  public UnifiedData adapt(Map<String, Object> rawData) {
    UnifiedData data = new UnifiedData();
    // 老版本字段名是 "page_name"，新版本统一用 "page_id"
    data.setPageId((String) rawData.get("page_name"));
    // 老版本没有 duration，给默认值
    data.setDuration(rawData.containsKey("duration") ? 
                     ((Number) rawData.get("duration")).intValue() : 0);
    return data;
  }
}

// v3.1 适配器
class V3_1Adapter implements DataAdapter {
  @Override
  public boolean supports(String version) {
    return version.startsWith("3.1");
  }

  @Override
  public UnifiedData adapt(Map<String, Object> rawData) {
    UnifiedData data = new UnifiedData();
    data.setPageId((String) rawData.get("page_id"));
    data.setDuration(((Number) rawData.get("duration")).intValue());
    return data;
  }
}

4.4 字段兼容的“三原则”

设计数据字段时，我给自己定了三条铁律：

这三条原则，说白了就是对新版本宽容，对老版本友好。我在项目中遇到过因为删了一个老字段，导致十几个旧版本App数据全部丢失的惨案。从那以后，“只增不减”就成了我的底线。

4.5 兼容性测试：别等上线了才发现

兼容方案写好了，不测试等于白写。我一般会准备一个版本兼容矩阵：

测试用例要覆盖：

• 老版本SDK发数据给新版本服务端
• 新版本SDK发数据给老版本服务端（如果服务端没升级）
• 字段缺失、类型异常、空值等边界情况

4.6 兼容方案整体架构

下面这张图是我常用的兼容方案架构，你可以参考：

从这张图你能看到，数据从不同版本的SDK发出后，先进入统一信封，然后根据版本号路由到对应的适配器。每个适配器只关心自己版本的转换逻辑，互不干扰。这样就算以后来了v4.0、v5.0，加个新适配器就行，老代码完全不用动。