@JsonFormat格式化日期

1. 核心作用

• 日期格式化：将 Date/LocalDateTime 等类型字段按指定格式转换为字符串
• 时区控制：解决时区不一致导致的日期偏差问题
• 数值格式化：控制数字的显示格式（如小数位数）

---

2. 常用场景

场景 1：日期格式化

import com.fasterxml.jackson.annotation.JsonFormat;
public class Order {@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")private Date createTime;@JsonFormat(pattern = "yyyy/MM/dd")private LocalDate deliveryDate;
}

• 序列化结果：

  {"createTime": "2023-10-05 14:30:00","deliveryDate": "2023/10/06"
  }
  

场景 2：时区控制

@JsonFormat(pattern = "yyyy-MM-dd", timezone = "Asia/Shanghai")
private Date eventDate;

• 避免服务端与客户端时区不一致导致的时间偏差

场景 3：数值格式化

@JsonFormat(shape = JsonFormat.Shape.STRING) // 将数值序列化为字符串
private Long productId;@JsonFormat(shape = JsonFormat.Shape.NUMBER_FLOAT, pattern = "#,##0.00")
private BigDecimal price;

---

3. 关键参数详解

参数名	说明
pattern	格式模板（如 yyyy-MM-dd）
timezone	时区设置（如 GMT+8 或 Asia/Shanghai）
shape	指定序列化形态：STRING/NUMBER/OBJECT 等
locale	地区设置（如 Locale.CHINA）
with	指定自定义格式化器（需实现 JsonFormat.Value）

---

4. 常见问题解决

问题 1：日期显示为时间戳

// 解决方案：明确指定格式
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date updateTime;

问题 2：LocalDateTime 报错

// 需要添加依赖：
implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310'// 在类上添加注解：
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
private LocalDateTime timestamp;

问题 3：时区不一致

// 强制指定时区
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "Asia/Tokyo")
private Date japanEventDate;

---

5. 高级用法

自定义形状 (Shape)

@JsonFormat(shape = JsonFormat.Shape.ARRAY) // 将对象序列化为数组
private Coordinate point;// 序列化结果：
// [120.5, 30.2] 而不是 {"x":120.5,"y":30.2}

枚举序列化控制

@JsonFormat(shape = JsonFormat.Shape.OBJECT)
public enum Status {NEW(1, "新建"),PROCESSING(2, "处理中");// 枚举字段...
}

---

6. 最佳实践

1. 全局配置：在 application.yml 中设置默认格式（Spring Boot）

   spring:jackson:date-format: yyyy-MM-dd HH:mm:sstime-zone: GMT+8
   

2. 字段级覆盖：用 @JsonFormat 覆盖全局配置
3. 测试验证：使用 ObjectMapper 手动测试序列化结果

---

7. 完整示例

import com.fasterxml.jackson.annotation.JsonFormat;
public class Event {@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss",timezone = "Asia/Shanghai",shape = JsonFormat.Shape.STRING)private Date eventTime;@JsonFormat(shape = JsonFormat.Shape.NUMBER)private Long eventId;// Getters & Setters
}

通过合理使用 @JsonFormat，可以精准控制 Java 对象与 JSON 之间的数据格式转换，解决前后端数据交互中的格式痛点。