Jackson无法反序列化带根元素的JSON数组，报MismatchedInputException

错误原因分析 #

你遇到的MismatchedInputException源于两个核心问题：

1. 开启UNWRAP_ROOT_VALUE特性后，Jackson期望根节点名称与目标类型的默认根名称匹配。你试图直接反序列化为Builder[]类型，它的默认根名称是Builder[]，但JSON的根节点是builders，两者不匹配。
2. 你的JSON结构是外层对象包含一个名为builders的数组字段，而非直接以数组作为根节点，这和你直接反序列化数组的操作逻辑冲突。

解决方案 #

方案1：创建包装DTO类（推荐） #

新增一个包装类，直接对应JSON的外层结构：

public class BuilderWrapper {
    @JsonProperty("builders")
    private Builder[] builders;

    // Getter和Setter
    public Builder[] getBuilders() {
        return builders;
    }

    public void setBuilders(Builder[] builders) {
        this.builders = builders;
    }
}

修改反序列化代码，无需开启UNWRAP_ROOT_VALUE：

var json = response.body();
var wrapper = mapper.readValue(json, BuilderWrapper.class);
var builders = wrapper.getBuilders();

方案2：直接解析JSON节点（无需新增类） #

使用Jackson的JsonNode先解析整个JSON，再提取数组部分反序列化：

var json = response.body();
JsonNode rootNode = mapper.readTree(json);
JsonNode buildersNode = rootNode.get("builders");
Builder[] builders = mapper.treeToValue(buildersNode, Builder[].class);

额外优化点 #

• 移除Builder类上的@JsonRootName("builders")注解：该注解用于指定单个对象的根节点名称，不适用于数组场景。
• 统一类型匹配：Builder类中id字段定义为String，但JSON中id是数字类型，建议将id改为Integer类型，或者开启Jackson的数字转字符串自动转换特性，避免潜在类型转换问题。

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