Spring Boot 中 JSON 日期格式化详解

1. 概述

在本文中，我们将介绍如何在 Spring Boot 应用中对 JSON 日期字段进行格式化。

Spring Boot 默认使用 Jackson 作为 JSON 处理器，因此我们将基于 Jackson 提供的多种方式来实现日期格式控制。

2. 使用 @JsonFormat 格式化日期字段

2.1. 设置日期格式

我们可以使用 @JsonFormat 注解来对某个字段进行特定格式的序列化：

public class Contact {

    // 其他字段省略

    @JsonFormat(pattern="yyyy-MM-dd")
    private LocalDate birthday;
     
    @JsonFormat(pattern="yyyy-MM-dd HH:mm:ss")
    private LocalDateTime lastUpdate;

    // getter/setter 省略
}

在这个例子中，birthday 字段只展示日期部分，而 lastUpdate 则包含时间信息。

我们使用了 Java 8 的日期时间 API，这类类型在处理时间语义时更加清晰和安全。

当然，如果你还在使用老的 java.util.Date 类型，也可以同样使用该注解：

public class ContactWithJavaUtilDate {

     // 其他字段省略

     @JsonFormat(pattern="yyyy-MM-dd")
     private Date birthday;
     
     @JsonFormat(pattern="yyyy-MM-dd HH:mm:ss")
     private Date lastUpdate;

     // getter/setter 省略
}

最终输出的 JSON 内容如下所示：

{
    "birthday": "2019-02-03",
    "lastUpdate": "2019-02-03 10:08:02"
}

✅ 小结： 使用 @JsonFormat 是一种简单粗暴、针对性强的方式，适合用于个别字段的格式定制。

⚠️ 注意： 如果你需要统一整个项目中的日期格式，这种方式就显得有点“低效”了，后面我们会讲更优雅的做法。

2.2. 设置时区

如果你需要指定某个字段的时区，可以通过 @JsonFormat 的 timezone 属性设置：

@JsonFormat(pattern="yyyy-MM-dd HH:mm:ss", timezone="Europe/Zagreb")
private LocalDateTime lastUpdate;

⚠️ 如果字段类型本身就包含了时区信息（如 ZonedDateTime），则无需额外设置时区。

3. 配置全局默认日期格式

虽然 @JsonFormat 很方便，但硬编码格式和时区并不是长久之计。

如果想为整个应用配置统一的日期格式，可以在 application.properties 文件中进行如下配置：

spring.jackson.date-format=yyyy-MM-dd HH:mm:ss

还可以设置默认时区：

spring.jackson.time-zone=Europe/Zagreb

✅ 这种方式简单直接，适用于快速统一配置。

❌ 但有一个致命缺陷： 它对 Java 8 新的时间类型（如 LocalDate、LocalDateTime）不生效，仅支持 java.util.Date 和 java.util.Calendar。

4. 自定义 Jackson 的 ObjectMapper

如果我们既要使用 Java 8 时间类型，又要设置全局格式，那就要祭出终极武器了：自定义 ObjectMapper。

具体做法是创建一个实现了 Jackson2ObjectMapperBuilderCustomizer 接口的 Bean：

@Configuration
public class ContactAppConfig {

    private static final String dateFormat = "yyyy-MM-dd";
    private static final String dateTimeFormat = "yyyy-MM-dd HH:mm:ss";

    @Bean
    public Jackson2ObjectMapperBuilderCustomizer jsonCustomizer() {
        return builder -> {
            builder.simpleDateFormat(dateTimeFormat);
            builder.serializers(new LocalDateSerializer(DateTimeFormatter.ofPattern(dateFormat)));
            builder.serializers(new LocalDateTimeSerializer(DateTimeFormatter.ofPattern(dateTimeFormat)));
        };
    }

}

这段代码展示了如何为 Java 8 时间类型设置全局格式。虽然看起来稍微啰嗦了一点，但它同时兼容新旧时间类型，非常实用。

✅ 优点总结：

支持 Java 8 时间类型 ✅
可控性强，可扩展性好 ✅
统一管理，避免重复注解 ✅

5. 总结

在这篇文章中，我们介绍了多种在 Spring Boot 中对 JSON 日期字段进行格式化的方法：

方法	是否支持 Java 8 时间类型	是否全局生效	推荐场景
`@JsonFormat`	✅	❌	单个字段特殊格式
`application.properties`	❌	✅	快速统一旧类型格式
自定义 `ObjectMapper`	✅	✅	最佳实践，推荐使用

📌 建议： 生产环境中推荐使用自定义 ObjectMapper 的方式，既灵活又兼容性强，踩坑少。

Persistence

REST

Security