如何解决字段设为可空后出现的AvroTypeException未知联合分支问题

问题根源 #

将Avro Schema里的SecondLevel字段改为可空（类型设为[null, T]）后，旧JSON数据（直接存储字段值、无类型标记）会触发org.apache.avro.AvroTypeException: Unknown union branch异常。原因是Avro的JSON编码规则中，union类型的非第一个分支需要显式类型标记，旧数据未提供该标记；而Kafka使用二进制Avro序列化时自带类型元数据，因此不存在这个问题。

解决方案 #

调整Union类型的顺序 #

修改Avsc文件时，把非null的原始类型放在Union数组的第一位，null放在第二位。这样旧JSON数据的无标记值会被自动识别为第一个分支的类型，同时支持新场景下的null值输入，且无需修改字段名或JSON结构。

错误的Schema（导致旧数据报错）

{
  "type": "record",
  "name": "YourRecord",
  "fields": [
    {
      "name": "SecondLevel",
      "type": ["null", "string"] // null在第一位，旧数据无标记会被判定为未知分支
    }
  ]
}

修正后的Schema（兼容新旧数据）

{
  "type": "record",
  "name": "YourRecord",
  "fields": [
    {
      "name": "SecondLevel",
      "type": ["string", "null"] // 原始类型在第一位，null在后
    }
  ]
}

兼容的JSON数据示例 #

• 旧JSON数据（无需修改即可解析）：

  {
    "SecondLevel": "legacy-value"
  }
  

• 新JSON数据（支持null值）：

  {
    "SecondLevel": null
  }
  

为什么Kafka对接无问题？ #

Kafka生态中通常使用二进制Avro格式（搭配Schema Registry），这种序列化格式会在数据中嵌入完整的类型元信息，不受Avro JSON编码规则中Union顺序的限制，因此新旧数据都能被正确解析。只有纯JSON文件依赖Avro的JSON编码规则，才会出现兼容性问题。

内容的提问来源于stack exchange，提问作者Chris