Spring Boot 3.x 项目里，LocalDateTime 序列化别再乱用 @JsonFormat 了

Spring Boot 3.x 中 LocalDateTime 序列化的正确打开方式在 Spring Boot 3.x 和 Spring 6 的新生态中时间类型的处理方式发生了微妙但重要的变化。许多开发者习惯性地在每个 LocalDateTime 字段上添加 JsonFormat 注解这看似方便却隐藏着维护噩梦。本文将带你重新思考时间序列化的最佳实践。1. 为什么不再推荐字段级注解记得三年前接手的一个电商项目代码库里有 287 处 JsonFormat 注解分散在各个实体类中。当产品经理提出要统一修改时间格式时团队不得不进行全局搜索替换这种经历应该不少开发者都深有体会。字段级注解的核心问题维护成本高每个时间字段都需要单独配置格式变更时需要全量修改容易产生冲突当全局配置与字段注解共存时行为可能不一致缺乏统一性不同开发者可能使用不同格式导致 API 响应风格混乱// 典型的注解滥用示例 - 不推荐 public class Order { JsonFormat(pattern yyyy-MM-dd HH:mm) private LocalDateTime createTime; JsonFormat(pattern yyyy/MM/dd HH:mm:ss) private LocalDateTime payTime; }提示Spring Boot 3.x 默认使用 Jackson 2.14其对 JavaTimeModule 的处理逻辑有所优化这为我们采用全局方案提供了更好支持2. 全局配置的现代化方案2.1 基础配置方法在 application.yml 中最简单的全局配置spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: Asia/Shanghai但这种方式有两个局限仅影响 JSON 序列化不影响 RequestParam 等参数绑定无法为 LocalDate、LocalTime 等类型分别配置2.2 完整配置类方案更完善的解决方案是通过 JavaTimeModule 统一配置Configuration public class DateTimeConfig { Bean public ObjectMapper objectMapper() { ObjectMapper mapper new ObjectMapper(); JavaTimeModule module new JavaTimeModule(); module.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer( DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))); module.addSerializer(LocalDate.class, new LocalDateSerializer( DateTimeFormatter.ofPattern(yyyy-MM-dd))); module.addSerializer(LocalTime.class, new LocalTimeSerializer( DateTimeFormatter.ofPattern(HH:mm:ss))); mapper.registerModule(module) .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); return mapper; } }关键参数对比配置项作用域影响范围版本兼容性JsonFormat字段级JSON 序列化全版本spring.jackson.date-format全局JSON 序列化Boot 2.0JavaTimeModule全局全量控制需要 Jackson 2.103. 处理请求参数的时区陷阱在跨国业务中时区问题可能引发严重 bug。假设一个纽约用户提交订单时服务端默认按东八区处理就会产生 12 小时的时间偏差。解决方案Bean public WebMvcConfigurer dateTimeConfigurer() { return new WebMvcConfigurer() { Override public void addFormatters(FormatterRegistry registry) { DateTimeFormatter formatter DateTimeFormatter .ofPattern(yyyy-MM-dd HH:mm:ss) .withZone(ZoneId.systemDefault()); registry.addConverter(String.class, LocalDateTime.class, source - LocalDateTime.parse(source, formatter)); } }; }时区处理要点前端应始终传递带时区的时间字符串如 ISO-8601 格式后端存储统一使用 UTC 时间响应时根据用户所在时区转换4. 高级场景下的定制方案对于需要多种时间格式的复杂系统可以考虑以下扩展模式4.1 动态格式策略public class DynamicDateTimeSerializer extends JsonSerializerLocalDateTime { Override public void serialize(LocalDateTime value, JsonGenerator gen, SerializerProvider provider) throws IOException { String pattern determinePatternFromContext(); // 从线程上下文获取格式 gen.writeString(value.format(DateTimeFormatter.ofPattern(pattern))); } }4.2 多格式兼容处理Bean public ConverterString, LocalDateTime flexibleDateTimeConverter() { return source - { for (String pattern : Arrays.asList(yyyy-MM-dd HH:mm:ss, yyyy/MM/dd HH:mm, yyyyMMdd)) { try { return LocalDateTime.parse(source, DateTimeFormatter.ofPattern(pattern)); } catch (DateTimeParseException ignored) {} } throw new IllegalArgumentException(Unsupported date format); }; }在实际项目中我们采用了全局配置为主、特殊注解为辅的策略。核心业务实体使用统一格式只有确实需要特殊表现的字段如生日只需要年月日才使用字段级注解。这种平衡方案使系统既保持了统一性又保留了必要的灵活性。