@JsonFormat 只會轉日期？這四個高能用法太強大了
環境：SpringBoot3.4.2
1. 簡介
@JsonFormat 是 Jackson 框架中用于精準控制數據序列化與反序列化時輸出格式的注解，廣泛應用于日期、時間、數值等類型的格式轉換。它通過聲明式配置將 Java 對象屬性映射為符合業務需求的 JSON 結構，例如將 Date 類型轉為 "2025-12-31" 或帶時區的 "2025-12-31T23:59:59+08:00"。
盡管開發者普遍將 @JsonFormat 用于日期字段的格式化，但該注解的功能邊界遠不止于此。接下來，我們將介紹幾個其它非常強大的功能。
準備環境
public class User {
private Long id ;
private String firstName;
private String lastName;
private Date createTime = new Date();
// getters, settters, constructors
}定義一個Controller接口
@RestController
@RequestMapping("/users")
public class UserController {
@GetMapping("/{id}")
public ResponseEntity<User> query(@PathVariable Long id) {
return ResponseEntity.ok(new User(id, "pack", "xg", new Date())) ;
}
}2. 實戰案例
2.1 日期格式化
在默認情況下，訪問上面的接口輸出結果如下：
圖片
這其中的createTime日期字段默認使用的ISO 8601 標準中的擴展格式，該格式說明：
- 2025-04-26：日期部分（年-月-日）
- T：日期與時間的分隔符
- 01:47:11.428：時間部分（時:分:秒.毫秒）
- +00:00：時區偏移量（UTC+0）
這種默認的時間展示不符合我們的習慣（yyyy-MM-dd HH:mm:ss），并且時間還差了8小時，所有我們通常會采用如下的方式解決：
- 配置文件中定義格式及時區
spring:
jackson:
date-format: yyyy-MM-dd HH:mm:ss
time-zone: GMT+8- 使用@JsonFormat注解
@JsonFormat(
pattern = "yyyy-MM-dd HH:mm:ss",
timezone = "GMT+8")
private Date createTime = new Date();以上2種方式都能解決問題。
圖片
2.2 控制日期格式及錯誤自動修復
控制日期類型以數組形式輸出：
@JsonFormat(shape = Shape.ARRAY, timezone = "GMT+8")
private LocalDate date = LocalDate.now();輸出結果：
圖片
錯誤的日期自動修復。
圖片
我們可以通過如下的配置讓其自動修復。
@JsonFormat(
pattern = "yyyy-MM-dd HH:mm:ss"
timezone = "GMT+8",
lenient = OptBoolean.TRUE)
private Date createTime = new Date();輸出結果：
圖片
自動將日期修復到下一個合法的日期。
2.3 指定本地語言和類型
除了指定日期格式外，我們還可以指定序列化的地域。如果不指定該參數，就會使用默認的本地語言執行序列化：
指定本地語言
通過locale屬性指定地域，我們分別指定en，zh兩個地域。
@JsonFormat(pattern = "yyyy MMMM dd a", locale = "en")
private Date createTime = new Date();輸出結果：
圖片
輸出的英文 April（四月） 和 AM（上午）。
locale="zh" 輸出結果：
圖片
設置類型
如果你希望日期以數字（時間戳）方式輸出，那么你可以通過通過如下設置：
@JsonFormat(shape = Shape.NUMBER, timezone = "GMT+8")
private Date createTime = new Date();輸出結果：
2.4 忽略大小寫反序列化
我們并不能保證每次接收到的json數據格式都完全一樣的，可能出現屬性名稱大小寫規則并不統一。例如，上面User對象中的屬性firstName，可能接收到如下幾種情況：
- {"firstname": "John", ...}
- {"firstName": "John", ...}
- {"FIRSTNAME": "John", ...}
默認情況，當出現大小寫不一致情況會發生什么呢？
圖片
將firstname這里全小寫時，程序并不能識別到這種屬性。
在這種屬性key不一樣的情況，如果你希望也能正確的反序列化，那么你可以通過如下的方式配置：
@JsonFormat(
with = JsonFormat.Feature.ACCEPT_CASE_INSENSITIVE_PROPERTIES)
public class User {}我們通過with屬性來指定忽略大小寫。
圖片
2.5 處理枚舉類型
我們為上的User實體對象添加如下枚舉類型屬性：
public enum UserStatus {
ACTIVE("活躍", 100, true),
INACTIVE("不活躍", 101, false),
PENDING("待激活", 102, false);
private final String description;
private final int code;
private final boolean isActive;
UserStatus(String description, int code, boolean isActive) {
this.description = description;
this.code = code;
this.isActive = isActive;
}
public String getDescription() {
return description;
}
public int getCode() {
return code;
}
public boolean isActive() {
return isActive;
}
}修改User實體，添加UserStatus屬性。
public class User {
private UserStatus status ;
// ...
}默認輸出結果：
圖片
status屬性肯定不是我們希望的結果，我們希望將該枚舉值對應的所有信息都輸出。所以，我們做如下的修改：
@JsonFormat(shape = JsonFormat.Shape.OBJECT)
public enum UserStatus {}輸出結果：
圖片
我們還可以通過配置告知枚舉序列化時調用toString方法。
spring:
jackson:
serialization:
write-enums-using-to-string: true修改UserStatus；
public enum UserStatus {
// ...
@Override
public String toString() {
return description + "/" + code + "/" + isActive ;
}
}輸出結果：
圖片
圖片
