解决 Jackson 反序列化字段名不匹配问题：从报错到实战Unrecognized field “Total“ (class com.ylink.health.djkHhis.vo.ExamList-CSDN博客

引言

在 Java 开发XML中，我们经常使用 Jackson 库来处理 JSON 数据的序列化和反序列化。然而，在实际开发中，由于 JSON 和 Java 对象的字段命名风格不一致（如大小写、is 前缀等），经常会出现 UnrecognizedPropertyException 错误。本文将结合一个实际案例，分析常见的字段名不匹配问题，并提供多种解决方案，帮助开发者高效应对类似问题。

问题背景

假设我们有一个 JSON 数据，结构如下：

{
    "id": null,
    "msg": null,
    "isSuccess": true,
    "code": null,
    "data": {
        "Total": 1700,
        "Rows": [...]
    }
}

对应的 Java 类 ExamListResponseVo 定义如下：

@Data
public class ExamListResponseVo {
    private Object id;
    private String msg;
    private boolean isSuccess; // 问题1：Jackson 默认会去掉 is 前缀
    private Object code;
    private ExamListData data;

    @Data
    public static class ExamListData {
        private Integer total; // 问题2：JSON 中是 "Total"，大小写不匹配
        private List<ExamRow> rows;
    }
}

当我们使用 ObjectMapper 反序列化时，可能会遇到以下两个错误：

error：Unrecognized field "isSuccess"

原因：isSuccess 在 JSON 中是 isSuccess，但 Jackson 默认会去掉 is 前缀，尝试匹配 success。

error：Unrecognized field "Total"

原因：JSON 中的 "Total" 是首字母大写，而 Java 类中是 total，大小写不匹配。

解决方案

1. 解决 `isSuccess` 问题

方案 1：修改 Java 字段名（推荐）

private boolean success; // 改为 success，与 Jackson 默认行为一致

方案 2：使用 `@JsonProperty` 注解

@JsonProperty("isSuccess") // 强制匹配 JSON 中的 isSuccess
private boolean isSuccess;

方案 3：配置 `ObjectMapper` 禁用 `is` 前缀处理

ObjectMapper mapper = new ObjectMapper();
mapper.configure(MapperFeature.USE_STD_BEAN_NAMING, true); // 禁止自动去掉 is 前缀

2. 解决 `Total` 大小写问题

方案 1：修改 Java 字段名（推荐）

private Integer Total; // 与 JSON 完全一致

方案 2：使用 `@JsonProperty` 注解

@JsonProperty("Total")
private Integer total;

方案 3：配置 `ObjectMapper` 忽略大小写

ObjectMapper mapper = new ObjectMapper();
mapper.configure(MapperFeature.ACCEPT_CASE_INSENSITIVE_PROPERTIES, true);

方案 4：忽略未知字段（适用于不可控 JSON 结构）

@Data
@JsonIgnoreProperties(ignoreUnknown = true) // 忽略 JSON 中多余的字段
public static class ExamListData {
    private Integer total;
    private List<ExamRow> rows;
}

最佳实践

1. 保持 JSON 和 Java 字段名一致

如果 JSON 可控，建议统一命名风格，如全部使用 snake_case 或 camelCase。

2. 优先使用 `@JsonProperty` 注解

适用于需要保留原有 Java 字段名但 JSON 字段名不同的情况。

3. 全局配置 `ObjectMapper`

如果项目中有大量大小写不一致的情况，可以全局配置：

ObjectMapper mapper = new ObjectMapper();
mapper.configure(MapperFeature.ACCEPT_CASE_INSENSITIVE_PROPERTIES, true);
mapper.configure(MapperFeature.USE_STD_BEAN_NAMING, true);

4. 使用 `@JsonIgnoreProperties` 避免未知字段报错

适用于第三方 API 返回的 JSON 结构可能变化的情况。

完整代码示例

修正后的 `ExamListResponseVo`

@Data
@JsonIgnoreProperties(ignoreUnknown = true) // 可选：忽略未知字段
public class ExamListResponseVo {
    private Object id;
    private String msg;
    @JsonProperty("isSuccess") // 显式指定 JSON 字段名
    private boolean isSuccess;
    private Object code;
    private ExamListData data;

    @Data
    public static class ExamListData {
        @JsonProperty("Total") // 显式指定 JSON 字段名
        private Integer total;
        private List<ExamRow> rows;
    }
}

反序列化代码

ObjectMapper mapper = new ObjectMapper();
// 可选：全局配置
// mapper.configure(MapperFeature.ACCEPT_CASE_INSENSITIVE_PROPERTIES, true);

String responseBody = "..."; // JSON 字符串
ExamListResponseVo result = mapper.readValue(responseBody, ExamListResponseVo.class);

总结

问题	解决方案	适用场景
`isSuccess` 不匹配	修改字段名 / `@JsonProperty`	布尔字段带 `is` 前缀
`Total` 大小写问题	修改字段名 / `@JsonProperty` / 全局配置	JSON 字段名大小写不一致
未知字段报错	`@JsonIgnoreProperties`	第三方 API 返回不可控 JSON