---
URL: "/zh-CN/blog/2026-04/Jackson.html"
LLMS_URL: "/zh-CN/blog/2026-04/Jackson.md"
lastUpdated: true
commentabled: true
recommended: true
title: "解决 Jackson 反序列化字段名不匹配问题"
description: "解决 Jackson 反序列化字段名不匹配问题"
date:

pageClass: "blog-page-class"
cover: "/covers/java.svg"
---

---
lastUpdated: true
commentabled: true
recommended: true
title: 解决 Jackson 反序列化字段名不匹配问题
description: 解决 Jackson 反序列化字段名不匹配问题
date: 2026-04-30 11:34:00 
pageClass: blog-page-class
cover: /covers/java.svg
---

## 引言 ##

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

## 问题背景 ##

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

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

对应的 Java 类 `ExamListResponseVo` 定义如下：

```java
@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，大小写不匹配。

## 解决方案 ##

### 解决 isSuccess 问题 ###

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

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

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

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

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

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

### 解决 Total 大小写问题 ###

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

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

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

```java
@JsonProperty("Total")
private Integer total;
```

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

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

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

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

## 最佳实践 ##

### 保持 JSON 和 Java 字段名一致 ###

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

### 优先使用 @JsonProperty 注解 ###

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

### 全局配置 ObjectMapper ###

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

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

### 使用 @JsonIgnoreProperties 避免未知字段报错 ###

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

## 完整代码示例 ##

### 修正后的 `ExamListResponseVo` ###

```java
@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;
    }
}
```

### 反序列化代码 ###

```java
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   |

*推荐做法*：

- 尽量统一 JSON 和 Java 字段名（如 camelCase）。

- 必要时使用 `@JsonProperty` 显式映射。

- 全局配置 `ObjectMapper` 适用于大型项目。

- 使用 `@JsonIgnoreProperties` 增强鲁棒性。

通过本文的解决方案，你可以轻松应对 Jackson 反序列化时的字段名不匹配问题，提高开发效率！