Spring Boot中HTTP請求參數轉換和請求體JSON反序列化的區別

問題

假設如下方法和對象

@Operation(summary = "新增或修改標籤信息")
@PostMapping("saveOrUpdate")
public Result saveOrUpdateLabel(@RequestBody LabelInfo labelInfo) {
    service.saveOrUpdate(labelInfo);
    return Result.ok();
}

@Schema(description = "標籤信息表")
@TableName(value = "label_info")
@Data
public class LabelInfo extends BaseEntity {

    private static final long serialVersionUID = 1L;

    @Schema(description = "類型")
    @TableField(value = "type")
    private ItemType type;

    @Schema(description = "標籤名稱")
    @TableField(value = "name")
    private String name;
}

@Getter
@AllArgsConstructor
public enum ItemType implements BaseEnum {
    APARTMENT(1, "公寓"),
    ROOM(2, "房間");

    @EnumValue
    @JsonValue
    private Integer code;

    private String name;
}

在saveOrUpdateLabel方法中，如果不對ItemType對象的code變量添加@JsonValue註解，若前端發送{ "type": "2", "name": "兩室一廳" }會報錯

Resolved [org.springframework.http.converter.HttpMessageNotReadableException: JSON parse error: Cannot deserialize value of type `com.sense.lease.model.enums.ItemType` from String "2": not one of the values accepted for Enum class: [APARTMENT, ROOM]]

此時ItemType的反序列化流程是什麼樣的？以及為什麼是通過Jackson的@JsonValue實現反序列化而不是WebDataBinder的Converter？

1. 兩種不同的轉換場景

首先，我們需要區分兩種不同的轉換場景：

1. HTTP請求參數轉換：
   • 場景：URL查詢參數或表單數據，如?type=2
   • 處理器：Spring MVC的WebDataBinder和Converter接口
   • 轉換方向：String → Java對象
2. JSON反序列化：
   • 場景：請求體中的JSON數據，如{"type": "2", "name": "兩室一廳"}
   • 處理器：Jackson庫的ObjectMapper
   • 轉換方向：JSON字符串 → Java對象

2. JSON反序列化流程詳解

當Spring Boot接收到包含JSON的請求體時，會發生以下過程：

1. HTTP請求到達：

   POST /admin/label/saveOrUpdate
   Content-Type: application/json
   
   {
     "type": "2",
     "name": "兩室一廳"
   }
   

2. Jackson處理JSON：

   • Spring Boot使用Jackson的ObjectMapper來解析JSON
   • 當遇到"type": "2"時，Jackson需要將其轉換為ItemType枚舉

3. 默認枚舉反序列化：

   • Jackson默認使用枚舉的名稱進行反序列化
   • 它會嘗試匹配"2"與枚舉常量名稱：[APARTMENT, ROOM]
   • 由於沒有名為"2"的枚舉常量，所以拋出異常

3. @JsonValue註解的作用

@JsonValue註解告訴Jackson在進行序列化和反序列化時，應該使用哪個字段作為枚舉的值：

public enum ItemType implements BaseEnum {
    APARTMENT(1, "公寓"),
    ROOM(2, "房間");

    @EnumValue  // MyBatis-Plus使用此註解確定存儲到數據庫的值
    @JsonValue  // Jackson使用此註解確定序列化/反序列化的值
    private Integer code;
    
    // ...
}

當添加了@JsonValue註解後：

1. 序列化：將ItemType.ROOM轉換為JSON時，輸出2而不是"ROOM"
2. 反序列化：將JSON中的字符串"2"或者數字2轉換為ItemType.ROOM對象

4. 為什麼Converter不適用於JSON反序列化

Converter接口（如StringToItemTypeConverter）是為Spring MVC的WebDataBinder設計的，專門用於處理HTTP請求參數的轉換，而不是JSON數據的反序列化。

兩者的工作層面不同：

1. Converter：
   • 工作在Spring MVC層面
   • 處理HTTP請求參數（查詢參數、表單數據）
   • 在控制器方法參數綁定之前執行
2. Jackson的反序列化：
   • 工作在JSON處理層面
   • 處理請求體中的JSON數據
   • 在控制器方法參數綁定之前執行，但獨立於Spring MVC的轉換機制

5. 驗證這個區別

可以通過以下方式驗證這個區別：

1. 測試請求參數（使用Converter）：

   GET /admin/label/list?type=2
   

   這個請求會使用StringToItemTypeConverter進行轉換

2. 測試JSON請求體（使用@JsonValue）：

   POST /admin/label/saveOrUpdate
   Content-Type: application/json
   
   {
     "type": "2",
     "name": "兩室一廳"
   }
   

   這個請求會使用Jackson的反序列化機制，依賴於@JsonValue註解

6. 替代方案：@JsonCreator註解

除了使用@JsonValue，您還可以使用@JsonCreator註解提供自定義的反序列化方法：

// @JsonCreator註解指定自定義反序列化方法，靜態工廠函數，根據code屬性值返回對應的枚舉對象實例
// 參數類型需與Json數據中code屬性的數據類型一致，或者聲明為Object類型，否則無法將json數據與參數綁定
// 參數名可直接使用Json數據中的屬性名，否則需使用@JsonProperty註解指定屬性名。
@JsonCreator
public static ItemType forValue(@JsonProperty("code") String c) {
    for (ItemType type : ItemType.values()) {
        if (type.getCode().equals(Integer.valueOf(c))) {
            return type;
        }
    }
    throw new IllegalArgumentException("code: " + c + "非法");
}

優點：靈活，可進行額外的處理流程

缺點：

1. 繁瑣，需要為每個枚舉類單獨實現
2. 需要注意參數的變量類型和變量名與JSON數據是否對應，否則無法觸發；而@JsonValue註解時，JSON數據既可以是字符串也可以是數字

總結

• HTTP請求參數轉換：使用Converter接口，由Spring MVC的WebDataBinder處理
• JSON反序列化：使用Jackson的機制，依賴於@JsonValue或@JsonCreator註解，不僅是請求體中的JSON數據反序列化，任何時候涉及到JSON數據反序列化，只要使用的是Spring Boot默認的ObejctMapper或配置了相同Jackson設置的ObejctMapper，相關注解都會生效。
• 兩者是獨立的機制，解決不同場景下的類型轉換問題
• 為了完整支持兩種場景，需要同時提供Converter和適當的Jackson註解