Jackson中修改类数据类型后的反序列化兼容处理最佳实践

当你把现有类A的names字段从List<String>改成Map<String, List<String>>时，未同步更新的客户端会因类型不匹配出现反序列化失败。以下是几种简洁可行的处理方案：

• 兼容过渡方案（推荐）
  保留原List<String> names字段，新增Map<String, List<String>> newNames字段，同时在类中添加转换逻辑：

  • 序列化时，优先输出newNames，可选保留names字段做兼容；
  • 反序列化时，若收到List<String>类型的names，自动转换为Map（比如用"default"作为默认键存储原列表）；若收到Map类型的输入，直接赋值给newNames。
    代码示例：

  public class ClassA {
      String id;
      // 保留原字段做兼容，非空时才序列化
      @JsonInclude(JsonInclude.Include.NON_NULL)
      List<String> names;
      Map<String, List<String>> newNames;
  
      // 反序列化时自动识别输入类型并转换
      @JsonSetter("names")
      public void setNames(Object value) {
          if (value instanceof List) {
              this.names = (List<String>) value;
              this.newNames = Collections.singletonMap("default", this.names);
          } else if (value instanceof Map) {
              this.newNames = (Map<String, List<String>>) value;
          }
      }
  
      // 序列化时统一输出Map类型的字段
      @JsonGetter("names")
      public Map<String, List<String>> getNames() {
          return newNames;
      }
  }
  

  等所有客户端完成更新后，再逐步移除原names字段。

• 版本化API
  为更新后的类A创建新的API版本（比如/v2），原API版本（/v1）继续使用旧的类A定义。客户端可以逐步迁移到新API，旧版本服务在过渡期后再下线。

• 自定义反序列化器
  针对names字段编写自定义Jackson反序列化器，自动识别输入的类型是List还是Map并完成转换：

  public class NamesDeserializer extends JsonDeserializer<Map<String, List<String>>> {
      @Override
      public Map<String, List<String>> deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {
          JsonNode node = p.getCodec().readTree(p);
          Map<String, List<String>> result = new HashMap<>();
          if (node.isArray()) {
              List<String> namesList = new ArrayList<>();
              for (JsonNode item : node) {
                  namesList.add(item.asText());
              }
              result.put("default", namesList);
          } else if (node.isObject()) {
              Iterator<Map.Entry<String, JsonNode>> fields = node.fields();
              while (fields.hasNext()) {
                  Map.Entry<String, JsonNode> entry = fields.next();
                  List<String> values = new ArrayList<>();
                  for (JsonNode val : entry.getValue()) {
                      values.add(val.asText());
                  }
                  result.put(entry.getKey(), values);
              }
          }
          return result;
      }
  }
  

  之后在类的字段上标注注解即可：

  public class ClassA {
      String id;
      @JsonDeserialize(using = NamesDeserializer.class)
      Map<String, List<String>> names;
  }
  

如果不想新增字段，自定义反序列化器是最直接的简洁方案，仅需一个自定义类加注解就能兼容两种输入类型；如果需要兼顾新旧客户端的序列化输出，兼容过渡方案更稳妥，能保证新旧客户端都能正常解析数据。

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