SpringBoot接口返回LocalDateTime时报错“Java 8 date/time typejava.time.LocalDateTimenot supported by default”这应该是每个用Java 8日期API的开发者都遇到过的日期序列化问题。很多新手第一次看到这个报错会以为是自己代码写错了翻来覆去找不出原因其实问题出在Jackson框架默认不认识java.time包下的新类型。今天这篇就把这个问题的来龙去脉讲透从报错原理、默认行为差异到全局配置、自定义序列化器、请求参数反序列化、时区偏移再到我亲测过的排查思路和避坑经验。无论你是刚入行的初级工程师还是正在维护老项目的同学这篇文章都可以直接当排查手册用。1. 先弄明白LocalDateTime序列化的底层报错1.1 这条报错到底在说什么先看报错原文Java 8 date/time type java.time.LocalDateTime not supported by default: add Module com.fasterxml.jackson.datatype:jackson-datatype-jsr310 to enable handling这句话拆开看就两层意思Jackson本身对java.time包下的LocalDateTime、LocalDate、LocalTime这些类型没有内建处理能力它不认识它们。Jackson提供了一个扩展模块叫jackson-datatype-jsr310也就是常说的JavaTimeModule只要你不把它注册到ObjectMapper里它就默认不启用碰到这类类型就直接抛异常。很多人会疑惑为什么java.util.Date就能正常转换LocalDateTime却不行因为在Java 8之前Java世界里通用的日期类型是java.util.Date、java.util.CalendarJackson老早就有对应的序列化器。而java.time包是Java 8才引入的全新日期时间APIJackson要想支持它必须通过模块机制加载对应的序列化器和反序列化器。这就像一个老牌工具箱里面的老工具都配了说明书新买回来的工具虽然好用但你不把它的说明书放进工具箱使用时就会提示“没有可用说明”。问题本质不是工具坏了是模块没加载。1.2 不加载JavaTimeModule时会出现哪些现象我在实际项目里见过三种表现你至少会碰到一种第一种就是报错直接抛出接口500日志里出现上面的not supported by default。这种在Spring Boot 2.0之前的版本里非常常见因为那时候Spring Boot的自动配置还没有默认注册jsr310模块。第二种更隐蔽接口不报错但返回给前端的时间是一串数组比如{ createTime: [2024, 3, 1, 14, 30, 0] }这是因为Jackson在没有找到合适的序列化器时会退回去把对象当作普通POJO处理LocalDateTime的内部字段被逐个拆出来输出。前端同学看到这种数据基本是懵的联调的时候会以为你接口写错了。第三种是会序列化但格式不可控有时是ISO字符串有时带T有时不带还有可能出现时区差8小时的问题。所以单靠Spring Boot 2.x自动配置里“默认已经引入jsr310依赖”还不够你还需要明确配置行为否则即使不报错返回格式也不符合业务预期。2. 全局搞定Spring Boot 2.x/3.x的JavaTimeModule配置2.1 先确认你项目里的Jackson模块在Spring Boot 2.x中spring-boot-starter-web默认传递依赖了jackson-datatype-jsr310也就是说你其实什么都不用额外引入包里已经有这个模块了。到了Spring Boot 3.x要求JDK 17起步但机制完全一样依赖同样默认携带。有些老项目或者自己手工搭建的SSM工程可能在pom里看不到这个依赖那就需要手动加dependency groupIdcom.fasterxml.jackson.datatype/groupId artifactIdjackson-datatype-jsr310/artifactId version2.15.2/version /dependency版本号以你自己项目的Jackson版本为准最好是直接继承Spring Boot父工程的依赖管理不要自己硬写版本号免得和SpringBoot内置版本不一致引发别的幺蛾子。2.2 用配置文件快速解决如果你的需求只是让LocalDateTime以字符串形式输出并且全局统一格式最省事的方式就是在application.yml里做如下配置spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8 serialization: write-dates-as-timestamps: false这里三个关键配置的作用分别是date-format设置的是日期格式但要注意它主要对java.util.Date生效对于LocalDateTime在Spring Boot 2.x中经常出现配置了却不生效的情况原因后面会讲。time-zone设置时区为东八区避免出现差8小时的尴尬。write-dates-as-timestamps: false用于关闭把日期写为时间戳数值的功能让日期按字符串输出而不是输出毫秒数或秒数。实测下来这套配置在Spring Boot 2.3以上版本里能解决大部分“返回数组”的问题因为Spring Boot自动配置时会把JavaTimeModule注册进ObjectMapper同时读取这些配置项。2.3 用配置类定制ObjectMapper一劳永逸配置文件不是万能的我强烈推荐你在项目里直接放一个Jackson配置类尤其是当团队有统一的日期格式规范时。下面这种基于Jackson2ObjectMapperBuilderCustomizer的写法是最稳妥的Configuration public class JacksonConfig { private static final DateTimeFormatter DATE_TIME_FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); Bean public Jackson2ObjectMapperBuilderCustomizer jacksonCustomizer() { return builder - { builder.serializerByType(LocalDateTime.class, new LocalDateTimeSerializer(DATE_TIME_FORMATTER)); builder.deserializerByType(LocalDateTime.class, new LocalDateTimeDeserializer(DATE_TIME_FORMATTER)); builder.featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); builder.featuresToDisable(DeserializationFeature.ADJUST_DATES_TO_CONTEXT_TIME_ZONE); }; } }之所以用Jackson2ObjectMapperBuilderCustomizer而不是直接new一个ObjectMapper是因为Spring Boot内部已经通过自动配置创建了ObjectMapper你如果自己再new一个容易把自动配置完全覆盖掉导致自定义配置和Spring Boot的默认行为打架。用这个回调接口Spring Boot会拿着你的定制器去增强它自己创建的那个ObjectMapper属于比较正规的扩展方式。这个方案的好处是你不用在每个字段上加注解全局所有LocalDateTime出参入参都走统一格式。项目如果不大格式规范也就这一条团队里没人再为“时间字段到底什么格式”吵架。2.4 JsonFormat局部字段救火队员全局配置是主流但总有例外。比如某个接口需要给前端返回毫秒级时间戳而全局配置的是yyyy-MM-dd HH:mm:ss你不可能为了一个字段改全局。这种情况下在字段上加JsonFormat注解是最快的Data public class OrderVO { private Long orderId; JsonFormat(pattern yyyy-MM-dd HH:mm:ss, timezone GMT8) private LocalDateTime createTime; JsonFormat(pattern timestamp, timezone GMT8) private LocalDateTime expireTime; }注意JsonFormat的优先级高于全局配置也就是说它是“局部覆盖全局”。测试的时候我确认过只要注解里写了pattern不管全局配置成什么样都以注解为准。还有一个常见的写法是在pattern里传timestamp可以输出时间戳数值。字段多的时候虽然注解显得啰嗦但它足够直观别人看代码一眼就知道这个字段返回什么格式。3. 自定义序列化器遇到复杂格式需求时的最终解法3.1 什么时候需要自己写序列化器全局配置和JsonFormat能覆盖大部分需求但如果你的项目对格式要求非常灵活或者需要同时支持多种日期格式反序列化就该考虑自定义序列化器和反序列化器了。我实际遇到过一个场景上游系统有的接口返回2024-03-01 14:30:00有的返回2024-03-01T14:30:00还有的直接返回时间戳数字。前端传参五花八门如果只用一种pattern反序列化时必挂。还有另一种典型场景团队要求出参全部是yyyy-MM-dd HH:mm:ss但入参允许前端传yyyy-MM-dd或者yyyy/MM/dd HH:mm:ss这种带斜杠的格式。这时自定义反序列化器是最好用的因为你可以在里面写一整套格式解析逻辑。3.2 完整实现本地时间序列化器与反序列化器先看序列化器逻辑很简单把LocalDateTime按指定格式写成字符串。public class LocalDateTimeSerializer extends JsonSerializerLocalDateTime { private final DateTimeFormatter formatter; public LocalDateTimeSerializer(DateTimeFormatter formatter) { this.formatter formatter; } Override public void serialize(LocalDateTime value, JsonGenerator gen, SerializerProvider serializers) throws IOException { gen.writeString(value.format(formatter)); } }再看反序列化器这里比序列化稍微复杂一点因为入参可能是标准字符串、带T的ISO字符串甚至是空字符串或null都要做好兼容public class LocalDateTimeDeserializer extends JsonDeserializerLocalDateTime { private static final DateTimeFormatter NORMAL_FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); private static final DateTimeFormatter DATE_FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-dd); private static final DateTimeFormatter SLASH_FORMATTER DateTimeFormatter.ofPattern(yyyy/MM/dd HH:mm:ss); Override public LocalDateTime deserialize(JsonParser p, DeserializationContext ctxt) throws IOException { String text p.getValueAsString(); if (text null || text.isEmpty() || null.equals(text)) { return null; } text text.trim(); try { if (text.contains(T)) { return LocalDateTime.parse(text, DateTimeFormatter.ISO_LOCAL_DATE_TIME); } if (text.contains(/)) { return LocalDateTime.parse(text, SLASH_FORMATTER); } if (text.length() 10) { LocalDate date LocalDate.parse(text, DATE_FORMATTER); return date.atStartOfDay(); } return LocalDateTime.parse(text, NORMAL_FORMATTER); } catch (DateTimeParseException e) { throw new IllegalArgumentException(无法解析的日期时间格式: text, e); } } }用DateTimeFormatter.ofPattern生成的实例是线程安全的所以可以直接定义为static不用担心并发问题。这点很多人忽略如果以后要做高并发接口自定义formatter尽量做成不可变共享实例不要每个请求都new一个。3.3 把自定义序列化器注入ObjectMapper写完了类还需要注册到ObjectMapper里才能生效。我习惯把它们和全局配置放一起Configuration public class JacksonConfig { Bean public Jackson2ObjectMapperBuilderCustomizer localDateTimeCustomizer() { return builder - { JavaTimeModule module new JavaTimeModule(); module.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))); module.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer()); builder.modules(module); builder.featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); }; } }这里用module.addSerializer往JavaTimeModule里“塞入”我们自己的序列化器比用builder.serializerByType更符合Jackson的推荐姿势。原因很简单LocalDateTime的序列化处理本身就由JavaTimeModule负责我们直接改写这个模块的内部映射而不是在外围用另一个序列化器覆盖它避免模块之间出现重复注册的冲突。同时这也能解释一个网上很常见的问题有人写了自定义序列化器也注册了但是不生效排查来排查去发现项目里有两个ObjectMapper或者另一个配置类里用Bean返回了ObjectMapper把全局的覆盖了。这种情况一定要检查所有Configuration类确保只有一个地方负责ObjectMapper定制。3.4 顺带把LocalDate和LocalTime也处理掉实际接口返回时字段类型绝不只是LocalDateTime一个LocalDate、LocalTime也经常出现。建议一次配置到位不然后面又是一轮报错。module.addSerializer(LocalDate.class, new LocalDateSerializer(DateTimeFormatter.ofPattern(yyyy-MM-dd))); module.addDeserializer(LocalDate.class, new LocalDateDeserializer(DateTimeFormatter.ofPattern(yyyy-MM-dd))); module.addSerializer(LocalTime.class, new LocalTimeSerializer(DateTimeFormatter.ofPattern(HH:mm:ss))); module.addDeserializer(LocalTime.class, new LocalTimeDeserializer(DateTimeFormatter.ofPattern(HH:mm:ss)));重点是让前端同事在接口文档里看到的日期格式是稳定的而不是今天返回数组明天返回字符串这才是序列化配置真正的价值。4. 请求参数的反向问题反序列化和时区4.1 返回没问题了前端传参又挂了全局配置好之后很多同学以为万事大吉结果第二天前端就在群里喊传参报错了。仔细看日志错误是Cannot deserialize value of type java.time.LocalDateTime from String 2024-03-01 14:30:00: Failed to deserialize java.time.LocalDateTime: (java.time.format.DateTimeParseException) Text 2024-03-01 14:30:00 could not be parsed原因很简单默认的JavaTimeModule虽然支持反序列化LocalDateTime但它默认能解析的是ISO格式的字符串比如2024-03-01T14:30:00。你给它一个空格格式的字符串它不认。解决方式就是用上一节的自定义反序列化器或者用JsonFormat注解指定pattern。不过要注意一个细节JsonFormat放在字段上时需要配合shape JsonFormat.Shape.STRING才比较保险写法如下JsonFormat(pattern yyyy-MM-dd HH:mm:ss, shape JsonFormat.Shape.STRING, timezone GMT8) private LocalDateTime enrollTime;如果只用pattern而不指定shape某些Jackson版本下反序列化时可能还是走默认解析器导致pattern不生效。这是我实测踩过的坑特此记一下。4.2 GET请求和表单提交的日期参数是另一条链路这里必须提醒一个容易混淆的地方Jackson只管JSON体RequestBody的序列化和反序列化而GET请求的?startTime2024-03-01 14:30:00、表单提交的application/x-www-form-urlencoded走的是Spring MVC的ConversionService和DateTimeFormat机制。所以如果你在Controller方法里这样写GetMapping(/list) public Result list(RequestParam(startTime) LocalDateTime startTime) { // ... }光配置Jackson是没用的必须用DateTimeFormat指定格式GetMapping(/list) public Result list( RequestParam(startTime) DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss) LocalDateTime startTime) { // ... }如果是POJO对象接收查询参数那就是在字段上加注解Data public class QueryDTO { DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss) private LocalDateTime startTime; DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss) private LocalDateTime endTime; }这块内容经常和Jackson配置混在一起讲导致很多人以为只要全局配了Jackson就能搞定一切参数实际不是。你至少要记住JSON body走Jacksonquery参数和form表单走Spring MVC的格式化器两边各管各的。4.3 时区差8小时问题怎么彻底根治时区问题的本质是全球时间标准UTC和本地时区的转换。服务器默认时区如果不是东八区你在本地写2024-03-01 00:00:00经过带时区的时间类型转换后返回给前端可能会变成2024-02-29 16:00:00。这个问题的经典场景是数据库连接串里写了serverTimezoneGMT%2B8Jackson配置也写了time-zone: GMT8但Java进程本身运行在UTC时区三个地方对不上。最稳妥的解决办法是在Spring Boot启动类或配置文件里统一时区。启动类里可以加PostConstruct public void initTimeZone() { TimeZone.setDefault(TimeZone.getTimeZone(Asia/Shanghai)); }注意PostConstruct执行顺序早于接口请求但晚于Spring容器初始化的一部分Bean所以如果某些Bean在构造时就用了时间可能还是旧的时区。更彻底的方式是在main方法里调用public static void main(String[] args) { TimeZone.setDefault(TimeZone.getTimeZone(Asia/Shanghai)); SpringApplication.run(Application.class, args); }容器部署时也可以在启动脚本里加上JVM参数java -Duser.timezoneAsia/Shanghai -jar app.jar如果你的服务部署在Docker中还必须检查宿主机和容器内时区是否一致很多线上差8小时问题最终定位出来是容器基础镜像默认UTC时区和代码没一点关系。5. 报错实录与线上排查技巧5.1 这4种报错你迟早会碰到我在接手的项目里见过各种奇奇怪怪的日期序列化报错这里整理成速查表方便你以后直接对号入座报错信息出现场景解决方案Java 8 date/time type LocalDateTime not supported by defaultSpring Boot 2.0以下或手动搭建的SSM工程引入jackson-datatype-jsr310并注册JavaTimeModuleNo serializer found for class java.time.LocalDateTimeObjectMapper没注册JavaTimeModule配置Jackson2ObjectMapperBuilderCustomizerCannot deserialize value of type LocalDateTime from String前端传的字符串不是ISO格式自定义反序列化器或JsonFormat(pattern)返回数组[2024, 3, 1, 14, 30, 0]JavaTimeModule没真正生效检查是否手动new了ObjectMapper添加module其中返回数组这个现象最有迷惑性因为接口不报错、日志无异常只有返回数据很奇怪。我在一个老项目里排查了很久最后发现是配置类里手动new了ObjectMapper并返回成BeanSpring Boot自己创建的ObjectMapper被忽略了我配置的WRITE_DATES_AS_TIMESTAMPSfalse根本没起作用。5.2 本地没问题线上却出错的排查顺序有一类问题特别坑本地开发一切正常部署到测试或生产环境就开始报日期解析错误。遇到这种情况我一般按下面顺序排查第一步检查环境依赖版本差异。本地用的JDK版本、Spring Boot版本、Maven打包的依赖树和生产是否一致。最典型的是本地JDK 17、生产JDK 8不同JDK自带的Jackson版本可能不相同行为就不一致。第二步检查配置文件是否被打进包里。application.yml里的spring.jackson配置如果在多环境中有覆盖确认生产环境用的配置文件确实包含日期配置。我用spring.profiles.active时遇到过配置文件配错前缀结果日期配置完全没被加载。第三步检查是否走了其他序列化框架。有些项目同时引入了fastjson全局消息转换器被替换成了fastjson的FastJsonHttpMessageConverter那Jackson配置再全也没用。这种时候要么移除fastjson要么单独给fastjson配置日期格式。5.3 我踩过的一个坑全局format不生效有一次项目组做接口联调我发现LocalDateTime全局已配置成yyyy-MM-dd HH:mm:ss但某个接口的子对象里时间字段还是输出的ISO字符串。查了很久才发现那个子对象里的日期字段被加上了JsonFormat(pattern yyyy-MM-ddTHH:mm:ss)注解优先级高于一切全局配置等于局部格式把全局格式覆盖了。这个案例说明一个团队规范问题日期格式最好在项目层面统一定义由JacksonConfig统一管理单个字段注解要尽量少用除非真的需要特例。不然同样的字段在不同接口里格式不一致前端联调起来会很痛苦。还有一次同事在网关服务里做报文日志打印打印出来的日期恢复成了数组格式。原因是网关服务和业务服务各自维护了一套Jackson配置业务服务配好了网关没配。如果你用了Spring Cloud Gateway或者单独的BFF层记得日期序列化配置要跟着服务走不能只在业务服务里配一次就完事。5.4 性能考量频繁序列化会不会有性能损失很多人担心加了自定义序列化器会影响性能尤其在高并发场景下。实测下来字符串格式化本身的开销远小于一次网络IO只要你的DateTimeFormatter是共享的、不频繁创建性能影响可以忽略不计。真正需要注意的反而是反序列化时的异常处理。不要在每个反序列化器里抛异常前打印堆栈日志否则瞬间大量坏请求会打爆日志系统。我习惯的做法是只抛IllegalArgumentException由全局异常处理器统一捕获并返回参数错误日志里只记录一条精简warning不打完整堆栈。还有个小细节如果你的对象里LocalDateTime字段特别多打开SerializationFeature.WRITE_DATES_AS_TIMESTAMPS关闭后序列化结果是字符串形式报文体积会变大一丢丢。如果对响应体大小极其敏感可以考虑全局用时间戳仅在个别字段用注解格式化字符串。这个取舍完全取决于业务场景没有绝对答案。最后再说一点个人体会。日期序列化问题看起来是个小事但它是前后端联调中踩坑频率最高的问题之一。与其每次报错了临时加注解不如在项目初始化时就统一规划好全局Jackson配置、请求参数格式化规则和时区策略这三个东西一次性配好后面几乎不会再来烦你。我现在的习惯是所有Java时间字段统一使用LocalDateTime不在业务代码里混用java.util.Date全局配置yyyy-MM-dd HH:mm:ss和东八区前端如果确实要传时间戳我再单独在注解里处理。这套规则从第一个SpringBoot项目沿用到现在基本没再为日期问题加过班。 
长河君 · 2026/10/1 4:46:52 · 阅读 1.2k SpringBoot中LocalDateTime序列化报错原因与全局配置解决方案
SpringBoot接口返回LocalDateTime时报错“Java 8 date/time typejava.time.LocalDateTimenot supported by default”这应该是每个用Java 8日期API的开发者都遇到过的日期序列化问题。很多新手第一次看到这个报错会以为是自己代码写错了翻来覆去找不出原因其实问题出在Jackson框架默认不认识java.time包下的新类型。今天这篇就把这个问题的来龙去脉讲透从报错原理、默认行为差异到全局配置、自定义序列化器、请求参数反序列化、时区偏移再到我亲测过的排查思路和避坑经验。无论你是刚入行的初级工程师还是正在维护老项目的同学这篇文章都可以直接当排查手册用。1. 先弄明白LocalDateTime序列化的底层报错1.1 这条报错到底在说什么先看报错原文Java 8 date/time type java.time.LocalDateTime not supported by default: add Module com.fasterxml.jackson.datatype:jackson-datatype-jsr310 to enable handling这句话拆开看就两层意思Jackson本身对java.time包下的LocalDateTime、LocalDate、LocalTime这些类型没有内建处理能力它不认识它们。Jackson提供了一个扩展模块叫jackson-datatype-jsr310也就是常说的JavaTimeModule只要你不把它注册到ObjectMapper里它就默认不启用碰到这类类型就直接抛异常。很多人会疑惑为什么java.util.Date就能正常转换LocalDateTime却不行因为在Java 8之前Java世界里通用的日期类型是java.util.Date、java.util.CalendarJackson老早就有对应的序列化器。而java.time包是Java 8才引入的全新日期时间APIJackson要想支持它必须通过模块机制加载对应的序列化器和反序列化器。这就像一个老牌工具箱里面的老工具都配了说明书新买回来的工具虽然好用但你不把它的说明书放进工具箱使用时就会提示“没有可用说明”。问题本质不是工具坏了是模块没加载。1.2 不加载JavaTimeModule时会出现哪些现象我在实际项目里见过三种表现你至少会碰到一种第一种就是报错直接抛出接口500日志里出现上面的not supported by default。这种在Spring Boot 2.0之前的版本里非常常见因为那时候Spring Boot的自动配置还没有默认注册jsr310模块。第二种更隐蔽接口不报错但返回给前端的时间是一串数组比如{ createTime: [2024, 3, 1, 14, 30, 0] }这是因为Jackson在没有找到合适的序列化器时会退回去把对象当作普通POJO处理LocalDateTime的内部字段被逐个拆出来输出。前端同学看到这种数据基本是懵的联调的时候会以为你接口写错了。第三种是会序列化但格式不可控有时是ISO字符串有时带T有时不带还有可能出现时区差8小时的问题。所以单靠Spring Boot 2.x自动配置里“默认已经引入jsr310依赖”还不够你还需要明确配置行为否则即使不报错返回格式也不符合业务预期。2. 全局搞定Spring Boot 2.x/3.x的JavaTimeModule配置2.1 先确认你项目里的Jackson模块在Spring Boot 2.x中spring-boot-starter-web默认传递依赖了jackson-datatype-jsr310也就是说你其实什么都不用额外引入包里已经有这个模块了。到了Spring Boot 3.x要求JDK 17起步但机制完全一样依赖同样默认携带。有些老项目或者自己手工搭建的SSM工程可能在pom里看不到这个依赖那就需要手动加dependency groupIdcom.fasterxml.jackson.datatype/groupId artifactIdjackson-datatype-jsr310/artifactId version2.15.2/version /dependency版本号以你自己项目的Jackson版本为准最好是直接继承Spring Boot父工程的依赖管理不要自己硬写版本号免得和SpringBoot内置版本不一致引发别的幺蛾子。2.2 用配置文件快速解决如果你的需求只是让LocalDateTime以字符串形式输出并且全局统一格式最省事的方式就是在application.yml里做如下配置spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8 serialization: write-dates-as-timestamps: false这里三个关键配置的作用分别是date-format设置的是日期格式但要注意它主要对java.util.Date生效对于LocalDateTime在Spring Boot 2.x中经常出现配置了却不生效的情况原因后面会讲。time-zone设置时区为东八区避免出现差8小时的尴尬。write-dates-as-timestamps: false用于关闭把日期写为时间戳数值的功能让日期按字符串输出而不是输出毫秒数或秒数。实测下来这套配置在Spring Boot 2.3以上版本里能解决大部分“返回数组”的问题因为Spring Boot自动配置时会把JavaTimeModule注册进ObjectMapper同时读取这些配置项。2.3 用配置类定制ObjectMapper一劳永逸配置文件不是万能的我强烈推荐你在项目里直接放一个Jackson配置类尤其是当团队有统一的日期格式规范时。下面这种基于Jackson2ObjectMapperBuilderCustomizer的写法是最稳妥的Configuration public class JacksonConfig { private static final DateTimeFormatter DATE_TIME_FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); Bean public Jackson2ObjectMapperBuilderCustomizer jacksonCustomizer() { return builder - { builder.serializerByType(LocalDateTime.class, new LocalDateTimeSerializer(DATE_TIME_FORMATTER)); builder.deserializerByType(LocalDateTime.class, new LocalDateTimeDeserializer(DATE_TIME_FORMATTER)); builder.featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); builder.featuresToDisable(DeserializationFeature.ADJUST_DATES_TO_CONTEXT_TIME_ZONE); }; } }之所以用Jackson2ObjectMapperBuilderCustomizer而不是直接new一个ObjectMapper是因为Spring Boot内部已经通过自动配置创建了ObjectMapper你如果自己再new一个容易把自动配置完全覆盖掉导致自定义配置和Spring Boot的默认行为打架。用这个回调接口Spring Boot会拿着你的定制器去增强它自己创建的那个ObjectMapper属于比较正规的扩展方式。这个方案的好处是你不用在每个字段上加注解全局所有LocalDateTime出参入参都走统一格式。项目如果不大格式规范也就这一条团队里没人再为“时间字段到底什么格式”吵架。2.4 JsonFormat局部字段救火队员全局配置是主流但总有例外。比如某个接口需要给前端返回毫秒级时间戳而全局配置的是yyyy-MM-dd HH:mm:ss你不可能为了一个字段改全局。这种情况下在字段上加JsonFormat注解是最快的Data public class OrderVO { private Long orderId; JsonFormat(pattern yyyy-MM-dd HH:mm:ss, timezone GMT8) private LocalDateTime createTime; JsonFormat(pattern timestamp, timezone GMT8) private LocalDateTime expireTime; }注意JsonFormat的优先级高于全局配置也就是说它是“局部覆盖全局”。测试的时候我确认过只要注解里写了pattern不管全局配置成什么样都以注解为准。还有一个常见的写法是在pattern里传timestamp可以输出时间戳数值。字段多的时候虽然注解显得啰嗦但它足够直观别人看代码一眼就知道这个字段返回什么格式。3. 自定义序列化器遇到复杂格式需求时的最终解法3.1 什么时候需要自己写序列化器全局配置和JsonFormat能覆盖大部分需求但如果你的项目对格式要求非常灵活或者需要同时支持多种日期格式反序列化就该考虑自定义序列化器和反序列化器了。我实际遇到过一个场景上游系统有的接口返回2024-03-01 14:30:00有的返回2024-03-01T14:30:00还有的直接返回时间戳数字。前端传参五花八门如果只用一种pattern反序列化时必挂。还有另一种典型场景团队要求出参全部是yyyy-MM-dd HH:mm:ss但入参允许前端传yyyy-MM-dd或者yyyy/MM/dd HH:mm:ss这种带斜杠的格式。这时自定义反序列化器是最好用的因为你可以在里面写一整套格式解析逻辑。3.2 完整实现本地时间序列化器与反序列化器先看序列化器逻辑很简单把LocalDateTime按指定格式写成字符串。public class LocalDateTimeSerializer extends JsonSerializerLocalDateTime { private final DateTimeFormatter formatter; public LocalDateTimeSerializer(DateTimeFormatter formatter) { this.formatter formatter; } Override public void serialize(LocalDateTime value, JsonGenerator gen, SerializerProvider serializers) throws IOException { gen.writeString(value.format(formatter)); } }再看反序列化器这里比序列化稍微复杂一点因为入参可能是标准字符串、带T的ISO字符串甚至是空字符串或null都要做好兼容public class LocalDateTimeDeserializer extends JsonDeserializerLocalDateTime { private static final DateTimeFormatter NORMAL_FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); private static final DateTimeFormatter DATE_FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-dd); private static final DateTimeFormatter SLASH_FORMATTER DateTimeFormatter.ofPattern(yyyy/MM/dd HH:mm:ss); Override public LocalDateTime deserialize(JsonParser p, DeserializationContext ctxt) throws IOException { String text p.getValueAsString(); if (text null || text.isEmpty() || null.equals(text)) { return null; } text text.trim(); try { if (text.contains(T)) { return LocalDateTime.parse(text, DateTimeFormatter.ISO_LOCAL_DATE_TIME); } if (text.contains(/)) { return LocalDateTime.parse(text, SLASH_FORMATTER); } if (text.length() 10) { LocalDate date LocalDate.parse(text, DATE_FORMATTER); return date.atStartOfDay(); } return LocalDateTime.parse(text, NORMAL_FORMATTER); } catch (DateTimeParseException e) { throw new IllegalArgumentException(无法解析的日期时间格式: text, e); } } }用DateTimeFormatter.ofPattern生成的实例是线程安全的所以可以直接定义为static不用担心并发问题。这点很多人忽略如果以后要做高并发接口自定义formatter尽量做成不可变共享实例不要每个请求都new一个。3.3 把自定义序列化器注入ObjectMapper写完了类还需要注册到ObjectMapper里才能生效。我习惯把它们和全局配置放一起Configuration public class JacksonConfig { Bean public Jackson2ObjectMapperBuilderCustomizer localDateTimeCustomizer() { return builder - { JavaTimeModule module new JavaTimeModule(); module.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))); module.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer()); builder.modules(module); builder.featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); }; } }这里用module.addSerializer往JavaTimeModule里“塞入”我们自己的序列化器比用builder.serializerByType更符合Jackson的推荐姿势。原因很简单LocalDateTime的序列化处理本身就由JavaTimeModule负责我们直接改写这个模块的内部映射而不是在外围用另一个序列化器覆盖它避免模块之间出现重复注册的冲突。同时这也能解释一个网上很常见的问题有人写了自定义序列化器也注册了但是不生效排查来排查去发现项目里有两个ObjectMapper或者另一个配置类里用Bean返回了ObjectMapper把全局的覆盖了。这种情况一定要检查所有Configuration类确保只有一个地方负责ObjectMapper定制。3.4 顺带把LocalDate和LocalTime也处理掉实际接口返回时字段类型绝不只是LocalDateTime一个LocalDate、LocalTime也经常出现。建议一次配置到位不然后面又是一轮报错。module.addSerializer(LocalDate.class, new LocalDateSerializer(DateTimeFormatter.ofPattern(yyyy-MM-dd))); module.addDeserializer(LocalDate.class, new LocalDateDeserializer(DateTimeFormatter.ofPattern(yyyy-MM-dd))); module.addSerializer(LocalTime.class, new LocalTimeSerializer(DateTimeFormatter.ofPattern(HH:mm:ss))); module.addDeserializer(LocalTime.class, new LocalTimeDeserializer(DateTimeFormatter.ofPattern(HH:mm:ss)));重点是让前端同事在接口文档里看到的日期格式是稳定的而不是今天返回数组明天返回字符串这才是序列化配置真正的价值。4. 请求参数的反向问题反序列化和时区4.1 返回没问题了前端传参又挂了全局配置好之后很多同学以为万事大吉结果第二天前端就在群里喊传参报错了。仔细看日志错误是Cannot deserialize value of type java.time.LocalDateTime from String 2024-03-01 14:30:00: Failed to deserialize java.time.LocalDateTime: (java.time.format.DateTimeParseException) Text 2024-03-01 14:30:00 could not be parsed原因很简单默认的JavaTimeModule虽然支持反序列化LocalDateTime但它默认能解析的是ISO格式的字符串比如2024-03-01T14:30:00。你给它一个空格格式的字符串它不认。解决方式就是用上一节的自定义反序列化器或者用JsonFormat注解指定pattern。不过要注意一个细节JsonFormat放在字段上时需要配合shape JsonFormat.Shape.STRING才比较保险写法如下JsonFormat(pattern yyyy-MM-dd HH:mm:ss, shape JsonFormat.Shape.STRING, timezone GMT8) private LocalDateTime enrollTime;如果只用pattern而不指定shape某些Jackson版本下反序列化时可能还是走默认解析器导致pattern不生效。这是我实测踩过的坑特此记一下。4.2 GET请求和表单提交的日期参数是另一条链路这里必须提醒一个容易混淆的地方Jackson只管JSON体RequestBody的序列化和反序列化而GET请求的?startTime2024-03-01 14:30:00、表单提交的application/x-www-form-urlencoded走的是Spring MVC的ConversionService和DateTimeFormat机制。所以如果你在Controller方法里这样写GetMapping(/list) public Result list(RequestParam(startTime) LocalDateTime startTime) { // ... }光配置Jackson是没用的必须用DateTimeFormat指定格式GetMapping(/list) public Result list( RequestParam(startTime) DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss) LocalDateTime startTime) { // ... }如果是POJO对象接收查询参数那就是在字段上加注解Data public class QueryDTO { DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss) private LocalDateTime startTime; DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss) private LocalDateTime endTime; }这块内容经常和Jackson配置混在一起讲导致很多人以为只要全局配了Jackson就能搞定一切参数实际不是。你至少要记住JSON body走Jacksonquery参数和form表单走Spring MVC的格式化器两边各管各的。4.3 时区差8小时问题怎么彻底根治时区问题的本质是全球时间标准UTC和本地时区的转换。服务器默认时区如果不是东八区你在本地写2024-03-01 00:00:00经过带时区的时间类型转换后返回给前端可能会变成2024-02-29 16:00:00。这个问题的经典场景是数据库连接串里写了serverTimezoneGMT%2B8Jackson配置也写了time-zone: GMT8但Java进程本身运行在UTC时区三个地方对不上。最稳妥的解决办法是在Spring Boot启动类或配置文件里统一时区。启动类里可以加PostConstruct public void initTimeZone() { TimeZone.setDefault(TimeZone.getTimeZone(Asia/Shanghai)); }注意PostConstruct执行顺序早于接口请求但晚于Spring容器初始化的一部分Bean所以如果某些Bean在构造时就用了时间可能还是旧的时区。更彻底的方式是在main方法里调用public static void main(String[] args) { TimeZone.setDefault(TimeZone.getTimeZone(Asia/Shanghai)); SpringApplication.run(Application.class, args); }容器部署时也可以在启动脚本里加上JVM参数java -Duser.timezoneAsia/Shanghai -jar app.jar如果你的服务部署在Docker中还必须检查宿主机和容器内时区是否一致很多线上差8小时问题最终定位出来是容器基础镜像默认UTC时区和代码没一点关系。5. 报错实录与线上排查技巧5.1 这4种报错你迟早会碰到我在接手的项目里见过各种奇奇怪怪的日期序列化报错这里整理成速查表方便你以后直接对号入座报错信息出现场景解决方案Java 8 date/time type LocalDateTime not supported by defaultSpring Boot 2.0以下或手动搭建的SSM工程引入jackson-datatype-jsr310并注册JavaTimeModuleNo serializer found for class java.time.LocalDateTimeObjectMapper没注册JavaTimeModule配置Jackson2ObjectMapperBuilderCustomizerCannot deserialize value of type LocalDateTime from String前端传的字符串不是ISO格式自定义反序列化器或JsonFormat(pattern)返回数组[2024, 3, 1, 14, 30, 0]JavaTimeModule没真正生效检查是否手动new了ObjectMapper添加module其中返回数组这个现象最有迷惑性因为接口不报错、日志无异常只有返回数据很奇怪。我在一个老项目里排查了很久最后发现是配置类里手动new了ObjectMapper并返回成BeanSpring Boot自己创建的ObjectMapper被忽略了我配置的WRITE_DATES_AS_TIMESTAMPSfalse根本没起作用。5.2 本地没问题线上却出错的排查顺序有一类问题特别坑本地开发一切正常部署到测试或生产环境就开始报日期解析错误。遇到这种情况我一般按下面顺序排查第一步检查环境依赖版本差异。本地用的JDK版本、Spring Boot版本、Maven打包的依赖树和生产是否一致。最典型的是本地JDK 17、生产JDK 8不同JDK自带的Jackson版本可能不相同行为就不一致。第二步检查配置文件是否被打进包里。application.yml里的spring.jackson配置如果在多环境中有覆盖确认生产环境用的配置文件确实包含日期配置。我用spring.profiles.active时遇到过配置文件配错前缀结果日期配置完全没被加载。第三步检查是否走了其他序列化框架。有些项目同时引入了fastjson全局消息转换器被替换成了fastjson的FastJsonHttpMessageConverter那Jackson配置再全也没用。这种时候要么移除fastjson要么单独给fastjson配置日期格式。5.3 我踩过的一个坑全局format不生效有一次项目组做接口联调我发现LocalDateTime全局已配置成yyyy-MM-dd HH:mm:ss但某个接口的子对象里时间字段还是输出的ISO字符串。查了很久才发现那个子对象里的日期字段被加上了JsonFormat(pattern yyyy-MM-ddTHH:mm:ss)注解优先级高于一切全局配置等于局部格式把全局格式覆盖了。这个案例说明一个团队规范问题日期格式最好在项目层面统一定义由JacksonConfig统一管理单个字段注解要尽量少用除非真的需要特例。不然同样的字段在不同接口里格式不一致前端联调起来会很痛苦。还有一次同事在网关服务里做报文日志打印打印出来的日期恢复成了数组格式。原因是网关服务和业务服务各自维护了一套Jackson配置业务服务配好了网关没配。如果你用了Spring Cloud Gateway或者单独的BFF层记得日期序列化配置要跟着服务走不能只在业务服务里配一次就完事。5.4 性能考量频繁序列化会不会有性能损失很多人担心加了自定义序列化器会影响性能尤其在高并发场景下。实测下来字符串格式化本身的开销远小于一次网络IO只要你的DateTimeFormatter是共享的、不频繁创建性能影响可以忽略不计。真正需要注意的反而是反序列化时的异常处理。不要在每个反序列化器里抛异常前打印堆栈日志否则瞬间大量坏请求会打爆日志系统。我习惯的做法是只抛IllegalArgumentException由全局异常处理器统一捕获并返回参数错误日志里只记录一条精简warning不打完整堆栈。还有个小细节如果你的对象里LocalDateTime字段特别多打开SerializationFeature.WRITE_DATES_AS_TIMESTAMPS关闭后序列化结果是字符串形式报文体积会变大一丢丢。如果对响应体大小极其敏感可以考虑全局用时间戳仅在个别字段用注解格式化字符串。这个取舍完全取决于业务场景没有绝对答案。最后再说一点个人体会。日期序列化问题看起来是个小事但它是前后端联调中踩坑频率最高的问题之一。与其每次报错了临时加注解不如在项目初始化时就统一规划好全局Jackson配置、请求参数格式化规则和时区策略这三个东西一次性配好后面几乎不会再来烦你。我现在的习惯是所有Java时间字段统一使用LocalDateTime不在业务代码里混用java.util.Date全局配置yyyy-MM-dd HH:mm:ss和东八区前端如果确实要传时间戳我再单独在注解里处理。这套规则从第一个SpringBoot项目沿用到现在基本没再为日期问题加过班。