如何处理不同JSON结构对应同一POJO的版本控制？含版本适配示例

这个问题在API版本演进中太常见了——既要迭代结构又要保证老版本的兼容性，我给你几个实用的方案，结合你的例子来拆解：

方案1：基于版本标识的自定义序列化/反序列化（轻量场景首选） #

如果你的API通过请求头（比如X-API-Version）或请求参数携带版本信息，最直接的方式是在序列化/反序列化阶段根据版本动态处理字段映射。以Jackson为例：

步骤1：调整核心Sample类，兼容多字段 #

让Sample同时持有name和field字段，通过自定义逻辑控制读写逻辑：

public class Sample {
    private String name;
    private Field field;

    // 构造器、基础getter/setter省略

    // 自定义反序列化：根据版本选择字段来源
    @JsonCreator
    public Sample(
            @JsonProperty("name") String name,
            @JsonProperty("field") Field field,
            @Contextual AttributeAccessor accessor) {
        // 从上下文获取版本号（需在框架层把请求头传入Jackson上下文）
        String apiVersion = accessor.getAttribute("X-API-Version").toString();
        
        if ("v2".equals(apiVersion)) {
            this.name = name;
        } else if ("v2.1".equals(apiVersion)) {
            this.name = field != null ? field.getName() : null;
            this.field = field;
        }
    }

    // 自定义序列化：根据版本输出对应结构
    @JsonValue
    public Object toJson(@Contextual AttributeAccessor accessor) {
        String apiVersion = accessor.getAttribute("X-API-Version").toString();
        if ("v2".equals(apiVersion)) {
            return Collections.singletonMap("name", this.name);
        } else if ("v2.1".equals(apiVersion)) {
            return Collections.singletonMap("field", this.field);
        }
        return null;
    }
}

public class Field {
    private String name;
    private int id;
    // getter/setter省略
}

步骤2：在框架中传递版本上下文 #

比如在Spring Boot里，你可以通过拦截器把请求头的版本号存入Jackson的序列化上下文，让上面的@Contextual能拿到版本信息。

方案2：版本化DTO + 模型转换（复杂场景首选） #

如果后续版本会持续迭代，直接修改核心Sample类会变得臃肿。这时候可以为每个版本定义独立的DTO，再统一转换到业务核心模型：

步骤1：定义版本专属DTO #

// v2版本DTO，对应原始JSON结构
public class SampleV2DTO {
    private String name;
    // getter/setter
}

// v2.1版本DTO，对应嵌套结构
public class SampleV21DTO {
    private Field field;
    // getter/setter
}

// 业务核心模型，与版本无关
public class SampleCore {
    private String name;
    private Integer id; // 从v2.1的field.id提取
    // getter/setter
}

步骤2：实现DTO到核心模型的转换 #

可以用MapStruct简化转换，也可以手动写转换器：

public class SampleConverter {
    public static SampleCore fromV2(SampleV2DTO dto) {
        SampleCore core = new SampleCore();
        core.setName(dto.getName());
        return core;
    }

    public static SampleCore fromV21(SampleV21DTO dto) {
        SampleCore core = new SampleCore();
        if (dto.getField() != null) {
            core.setName(dto.getField().getName());
            core.setId(dto.getField().getId());
        }
        return core;
    }
}

步骤3：在API层根据版本选择DTO #

比如在Spring Controller中：

@RestController
@RequestMapping("/sample")
public class SampleController {
    @Autowired
    private ObjectMapper objectMapper;

    @PostMapping
    public ResponseEntity<SampleCore> createSample(
            @RequestHeader("X-API-Version") String apiVersion,
            @RequestBody Object requestBody) {
        SampleCore core;
        if ("v2".equals(apiVersion)) {
            SampleV2DTO dto = objectMapper.convertValue(requestBody, SampleV2DTO.class);
            core = SampleConverter.fromV2(dto);
        } else if ("v2.1".equals(apiVersion)) {
            SampleV21DTO dto = objectMapper.convertValue(requestBody, SampleV21DTO.class);
            core = SampleConverter.fromV21(dto);
        } else {
            throw new IllegalArgumentException("Unsupported API version");
        }
        // 执行业务逻辑...
        return ResponseEntity.ok(core);
    }
}

方案3：序列化框架注解兼容（快速适配小版本变更） #

如果只是小版本的结构调整，也可以用Jackson的注解快速实现兼容，不用写太多自定义逻辑：

public class Sample {
    private String name;
    private Field field;

    // 反序列化时：优先读取name字段，若有field则用field.name覆盖
    @JsonProperty("name")
    public void setName(String name) {
        this.name = name;
    }

    @JsonProperty("field")
    public void setField(Field field) {
        this.field = field;
        if (field != null) {
            this.name = field.getName();
        }
    }

    // 序列化时：根据版本决定输出字段（需结合上下文获取版本）
    @JsonIgnore
    public String getName() { return name; }

    @JsonIgnore
    public Field getField() { return field; }

    @JsonAnyGetter
    public Map<String, Object> getSerializedFields(@Contextual AttributeAccessor accessor) {
        String apiVersion = accessor.getAttribute("X-API-Version").toString();
        Map<String, Object> fields = new HashMap<>();
        if ("v2".equals(apiVersion)) {
            fields.put("name", this.name);
        } else if ("v2.1".equals(apiVersion)) {
            fields.put("field", this.field);
        }
        return fields;
    }
}

这种方式适合快速兼容，但版本多了注解逻辑会混乱，更适合小范围的版本迭代。

总的来说：简单版本兼容选方案1或3；长期迭代、版本较多的场景，方案2的DTO分层更利于维护，能让核心业务模型不受版本细节干扰。

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