做后端开发这些年序列化这块踩过的坑真不少。早期用原生手写拼JSON字段一多就乱套后来换成Jackson一开始也只是停留在writeValueAsString和readValue两个方法上直到项目里遇到泛型反序列化、日期格式错乱、循环引用栈溢出、字段名对不上这些破事才被逼着把ObjectMapper从头到尾啃了一遍。这篇内容就是把这些年关于ObjectMapper的使用经验系统整理出来从配置、核心API、泛型处理、日期时间、循环引用、自定义序列化器到性能优化和常见问题排查全部讲透。不管你是刚接触Jackson的新手还是已经用过一段时间但总觉得配置不够顺手的老手应该都能从里面找到能直接抄作业的东西。核心关键词ObjectMapper会贯穿全文我会尽量用大白话加实际代码把每个点讲清楚让你看完就能在自己的项目里落地。1. 先搞清楚ObjectMapper到底是个什么东西1.1 它在整个序列化体系里的位置ObjectMapper是Jackson数据绑定模块的核心类负责Java对象和JSON字符串之间的双向转换。你可以把它理解成一个翻译官Java对象是中文JSON是英文ObjectMapper就是那个既懂中文又懂英文、还能按你的要求调整翻译风格的人。它内部依赖JsonParser和JsonGenerator完成底层的读写同时通过SerializerProvider和DeserializerProvider管理各种类型的序列化器和反序列化器。很多人以为ObjectMapper只是个工具类随便new一个就能用这个认知是第一个坑。ObjectMapper本身是线程安全的前提是你配置好之后不再修改它。官方文档明确说过一旦配置完成它可以被多个线程共享。但如果你在运行时动态调用setSerializationInclusion、configure这类方法就会破坏线程安全性。所以正确的做法是在应用启动时完成所有配置然后把它作为单例注入到需要的地方而不是每次用的时候都new一个。从依赖关系上看ObjectMapper属于jackson-databind模块它又依赖jackson-core和jackson-annotations。这三个包版本必须保持一致否则会出现NoSuchMethodError或者行为不一致的问题。我见过有项目里core是2.9、databind是2.13跑起来序列化结果莫名其妙丢字段排查了大半天才发现是版本冲突。所以第一件事先把版本对齐。1.2 为什么不用Gson或者Fastjson这个问题被问过很多次。客观说Gson轻量、API简单Fastjson在国内用得多、性能也不错但ObjectMapper的优势在于生态完整和扩展性强。Spring Boot默认集成JacksonSpring MVC的RequestBody和ResponseBody底层就是ObjectMapper在干活你用Spring就绕不开它。另外Jackson的注解体系非常丰富JsonProperty、JsonIgnore、JsonFormat、JsonSerialize这些注解能覆盖绝大多数定制需求自定义序列化器的接入也很顺滑。性能方面Jackson在流式处理和大对象场景下表现稳定配合ObjectReader和ObjectWriter复用可以进一步减少开销。Fastjson历史上出过一些安全漏洞Gson在复杂泛型处理上不如Jackson灵活。当然这不是说其他库不好而是说在Spring生态里ObjectMapper是阻力最小的选择。你如果项目里已经用了别的库没必要为了换而换但如果新项目跟着Spring走基本不会错。1.3 一个最小可用的配置模板先给一个我平时用的基础配置后面所有例子都基于这个模板展开ObjectMapper mapper new ObjectMapper(); // 反序列化时忽略JSON中多出来的字段避免上游加字段导致下游报错 mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); // 序列化时忽略值为null的字段 mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL); // 日期统一用ISO-8601格式不用时间戳 mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); // 枚举按名字序列化而不是序号 mapper.configure(SerializationFeature.WRITE_ENUMS_USING_TO_STRING, true);这几行配置解决了我遇到的大部分默认行为不符合预期的问题。FAIL_ON_UNKNOWN_PROPERTIES设为false尤其重要微服务之间字段增减很常见不关掉这个开关上游加个字段下游就炸了。NON_NULL能显著减小传输体积但要注意它只影响序列化反序列化时null字段照样能正常处理。2. 核心API逐个拆解别只会writeValueAsString2.1 序列化的几种姿势和适用场景ObjectMapper的序列化方法看着多其实按输出目标分三类转字符串、转字节数组、写文件或输出流。// 转字符串最常用 String json mapper.writeValueAsString(user); // 转字节数组适合网络传输或存Redis byte[] bytes mapper.writeValueAsBytes(user); // 写文件 mapper.writeValue(new File(user.json), user); // 写输出流适合Web响应 mapper.writeValue(response.getOutputStream(), user);选哪个取决于你的下游。转字符串最直观但字符串在内存里占的空间是字节的两倍左右大对象频繁序列化时用writeValueAsBytes更省内存。写文件的方式适合做数据导出但要注意它会覆盖原文件追加场景得自己控制流。还有一个容易被忽略的点writeValueAsString在遇到无法序列化的对象时会抛JsonProcessingException这是受检异常必须处理。很多人直接throws Exception往上抛结果在Controller层被全局异常处理器吞掉返回给前端一个500日志里却看不出具体是哪个字段出的问题。我的做法是捕获后把对象类型和字段信息拼进异常消息里排查时能省很多时间。2.2 反序列化的三种入口和泛型处理反序列化比序列化复杂因为Java的类型擦除机制导致泛型信息在运行时丢失。readValue(String, Class)只能处理简单类型遇到ListUser、MapString, ListUser这种嵌套泛型就抓瞎了。这时候要用TypeReference// 错误示范这样拿到的是ListLinkedHashMap不是ListUser ListUser wrong mapper.readValue(json, List.class); // 正确姿势用TypeReference保留泛型信息 ListUser users mapper.readValue(json, new TypeReferenceListUser() {}); // 嵌套泛型也没问题 MapString, ListUser map mapper.readValue(json, new TypeReferenceMapString, ListUser() {});TypeReference的原理是通过匿名子类在编译期把泛型信息写进class文件的签名里运行时通过反射拿到。注意它必须写成匿名内部类的形式写成new TypeReferenceListUser()后面不带花括号是不行的那样拿不到泛型参数。除了TypeReference还可以用JavaType适合需要动态构造类型的场景JavaType listType mapper.getTypeFactory() .constructCollectionType(List.class, User.class); ListUser users mapper.readValue(json, listType);JavaType的好处是可以在运行时根据配置动态拼类型比如从数据库读出来一个类型名字符串再反射构造对应的JavaType。TypeReference是编译期确定的JavaType是运行期构造的两者按需选用。2.3 树模型JsonNode的灵活读取有时候你不需要把JSON映射成具体对象只是想读其中几个字段或者JSON结构不固定这时候用树模型JsonNode最合适JsonNode root mapper.readTree(json); String name root.get(name).asText(); int age root.get(age).asInt(); // 遍历数组 JsonNode items root.get(items); for (JsonNode item : items) { System.out.println(item.get(id).asLong()); }JsonNode的好处是不需要预先定义类适合处理半结构化数据。但它也有代价每次get都是哈希查找大文档频繁读取性能不如直接映射成POJO。我的经验是字段少于五个、或者结构经常变的场景用JsonNode结构稳定的业务对象老老实实定义POJO。JsonNode还有几个实用方法path()和get()的区别在于path在字段不存在时返回MissingNode而不是null可以链式调用不抛NPEhas()判断字段是否存在isArray()、isObject()判断节点类型。这些在写防御性代码时很有用。2.4 对象转换convertValue的妙用convertValue是个被低估的方法它能把一个对象转成另一种类型中间走的是序列化加反序列化的流程// 把Map转成POJO MapString, Object map new HashMap(); map.put(name, 张三); map.put(age, 25); User user mapper.convertValue(map, User.class); // 把POJO转成Map MapString, Object result mapper.convertValue(user, Map.class);这个在对接第三方接口时特别有用对方返回的JSON你先用Map接住做一轮字段清洗和转换再convertValue成自己的业务对象。比直接映射成POJO再改字段要灵活。注意convertValue底层也是走完整的序列化反序列化性能不如直接映射高频调用场景要谨慎。3. 注解体系把定制化需求交给声明式配置3.1 字段级别的常用注解Jackson的注解是它最强大的部分大部分定制需求不用写代码加个注解就搞定。最常用的几个注解作用典型场景JsonProperty指定JSON字段名前后端字段命名风格不一致JsonIgnore序列化和反序列化都忽略密码、内部状态字段JsonIgnoreProperties类级别忽略多个字段忽略上游多余字段JsonFormat格式化日期、数字日期格式、时区JsonAlias反序列化时接受多个别名兼容上游字段改名JsonProperty(access)控制读写权限只读或只写字段JsonProperty最典型的用法是处理下划线和驼峰不一致的问题。比如数据库字段是user_nameJava属性是userName加个JsonProperty(user_name)就对齐了。JsonAlias则是反序列化时的多别名支持上游从user_name改成username你不想改代码加个别名就能同时兼容两种。JsonIgnore和JsonProperty(access Access.WRITE_ONLY)的区别要分清前者序列化和反序列化都忽略后者只在序列化时忽略、反序列化时仍然接收。密码字段通常用WRITE_ONLY前端传密码能接收返回用户信息时不带密码。3.2 类级别的注解和全局配置的优先级类级别注解里JsonIgnoreProperties(ignoreUnknown true)用得最多它等价于全局的FAIL_ON_UNKNOWN_PROPERTIESfalse但只对当前类生效。如果你的项目里大部分类都需要忽略未知字段用全局配置更省事如果只有个别类需要用类注解更精确。JsonNaming可以批量指定命名策略比如JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class)让整个类的字段都按蛇形命名序列化不用每个字段加JsonProperty。这个在对接Python或Go服务时特别方便因为那些语言习惯用下划线。注解和全局配置的优先级是注解优先于全局配置。比如全局设了NON_NULL但某个字段你想让它即使为null也输出加个JsonInclude(JsonInclude.Include.ALWAYS)就能覆盖。这个优先级规则要记牢排查序列化结果不符合预期时先看有没有注解覆盖了全局配置。3.3 自定义序列化器和反序列化器注解搞不定的场景就得上自定义序列化器。比如枚举你想序列化成自定义的code而不是name或者某个字段需要加密后输出public class SensitiveSerializer extends JsonSerializerString { Override public void serialize(String value, JsonGenerator gen, SerializerProvider provider) throws IOException { // 手机号脱敏138****1234 if (value ! null value.length() 11) { gen.writeString(value.substring(0, 3) **** value.substring(7)); } else { gen.writeString(value); } } } // 在字段上使用 public class User { JsonSerialize(using SensitiveSerializer.class) private String phone; }自定义反序列化器则是JsonDeserializer重写deserialize方法。注意反序列化器里要处理null和空字符串的情况否则容易抛NPE。另外自定义序列化器注册到ObjectMapper上有两种方式字段上打注解或者用SimpleModule全局注册。全局注册适合某个类型在所有地方都要特殊处理的情况比如统一处理所有枚举。SimpleModule module new SimpleModule(); module.addSerializer(MyEnum.class, new MyEnumSerializer()); mapper.registerModule(module);用SimpleModule注册时要注意注册顺序后注册的会覆盖先注册的。如果同时用了多个模块建议在启动时打印一下已注册的模块列表避免互相覆盖导致行为诡异。4. 日期时间处理最容易出问题的重灾区4.1 默认行为为什么坑ObjectMapper对java.util.Date的默认序列化是输出时间戳毫秒数对LocalDateTime默认输出数组形式[2024,1,15,10,30,0]。这两个默认行为几乎没人满意时间戳前端要自己转数组形式更是反人类。所以日期处理几乎是每个项目都要配置的。// 关闭时间戳输出 mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); // 注册Java 8时间模块 mapper.registerModule(new JavaTimeModule());JavaTimeModule是jackson-datatype-jsr310包提供的专门处理LocalDateTime、LocalDate、Instant这些Java 8时间类型。不注册这个模块直接序列化LocalDateTime会抛InvalidDefinitionException。这个包要单独引入依赖很多人只引了jackson-databind结果一用LocalDateTime就报错还以为是配置问题。4.2 全局日期格式和时区配置注册模块之后还要统一格式和时区SimpleModule module new JavaTimeModule(); // 自定义LocalDateTime的序列化和反序列化格式 DateTimeFormatter formatter DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); module.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(formatter)); module.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer(formatter)); mapper.registerModule(module); // 设置全局时区 mapper.setTimeZone(TimeZone.getTimeZone(Asia/Shanghai));时区这个点必须强调。服务器默认时区可能是UTC数据库存的是东八区时间序列化出来差8小时前端展示就错了。setTimeZone只影响Date和CalendarLocalDateTime本身不带时区信息所以格式化和时区要分开处理。我的建议是内部统一用LocalDateTime存不带时区的时间跨时区传输用Instant或带偏移量的OffsetDateTime展示层再按用户时区转换。4.3 字段级日期格式覆盖全局格式不一定满足所有字段比如大部分字段要yyyy-MM-dd HH:mm:ss但某个字段只要日期yyyy-MM-dd这时候用JsonFormat覆盖public class Order { JsonFormat(pattern yyyy-MM-dd HH:mm:ss, timezone GMT8) private LocalDateTime createTime; JsonFormat(pattern yyyy-MM-dd) private LocalDate deliveryDate; }JsonFormat的timezone属性对Date类型有效对LocalDateTime无效因为后者不带时区。这个细节很多人搞混配了timezone发现没生效其实是类型选错了。另外反序列化时如果前端传的格式和pattern对不上会抛InvalidFormatException错误信息里会带上期望格式和实际值排查时直接看这个信息就行。5. 循环引用和复杂对象图处理5.1 循环引用是怎么产生的双向关联的实体最容易出循环引用。比如User有ListOrderOrder又有个User引用序列化User时递归到Order又回到User无限递归直到栈溢出。错误信息通常是StackOverflowError或者JsonMappingException: Infinite recursion。这个问题在JPA/Hibernate项目里特别常见因为实体之间经常配双向关联。解决办法有三种各有适用场景。5.2 三种解决方案对比第一种是JsonIgnore在其中一个方向上忽略public class Order { JsonIgnore private User user; }简单粗暴但缺点是反序列化时这个字段也读不进来。如果只是序列化时想断开循环反序列化还需要这个字段就不能用这个。第二种是JsonManagedReference和JsonBackReference配对使用public class User { JsonManagedReference private ListOrder orders; } public class Order { JsonBackReference private User user; }JsonManagedReference标记的字段正常序列化JsonBackReference标记的字段序列化时被忽略但反序列化时能正常读入。这个方案适合父子关系明确的场景缺点是只能处理一对配对多个双向关联时容易配错。第三种是JsonIdentityInfo给每个对象加个标识重复出现时只输出标识JsonIdentityInfo(generator ObjectIdGenerators.PropertyGenerator.class, property id) public class User { private Long id; private ListOrder orders; }这个方案适合对象图复杂、多处引用的场景序列化结果里第二次出现的对象只输出id。缺点是前端解析时要自己处理引用关系而且如果对象没有唯一id字段就用不了。我的经验是简单的父子关系用JsonBackReference复杂对象图用JsonIdentityInfo临时应急用JsonIgnore。但根本上DTO和实体分离才是治本之道实体负责持久化DTO负责传输DTO里只放需要的字段从源头上避免循环引用。6. 性能优化别让序列化成为瓶颈6.1 ObjectMapper复用和ObjectWriter前面说过ObjectMapper是线程安全的配置好后可以全局复用。但每次调用writeValueAsString时它内部还是会做一些查找序列化器的开销。高频场景可以用ObjectWriter和ObjectReader预编译// 预编译writer适合固定类型的频繁序列化 ObjectWriter writer mapper.writerFor(User.class); String json writer.writeValueAsString(user); // 预编译reader ObjectReader reader mapper.readerFor(User.class); User user reader.readValue(json);ObjectWriter和ObjectReader是不可变对象创建后可以缓存复用内部已经绑定了类型信息省去了每次查找的开销。在QPS高的接口里这个优化能带来10%到20%的提升具体取决于对象复杂度。6.2 关闭不必要的特性ObjectMapper默认开启了一些你可能不需要的特性关掉能省点性能// 关闭自动检测getter显式用JsonProperty标注 mapper.disable(MapperFeature.AUTO_DETECT_GETTERS); // 关闭FAIL_ON_EMPTY_BEANS避免空对象报错 mapper.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS);AUTO_DETECT_GETTERS关掉后只有加了JsonProperty的字段才会被序列化好处是序列化范围可控坏处是每个字段都要加注解维护成本高。这个看团队习惯字段少的DTO可以关字段多的还是开着省事。FAIL_ON_EMPTY_BEANS建议关掉因为有些代理对象或者空集合序列化时会触发这个检查报错信息还不直观。关掉之后空对象序列化成{}比抛异常友好。6.3 大对象和流式处理处理超大JSON比如几百MB的导出文件时不要用writeValueAsString一次性加载到内存用流式APItry (JsonGenerator generator mapper.getFactory() .createGenerator(new FileOutputStream(big.json))) { generator.writeStartArray(); for (User user : userList) { mapper.writeValue(generator, user); } generator.writeEndArray(); }流式写入边读边写内存占用恒定。读取大文件同理用MappingIterator逐条读取try (MappingIteratorUser iterator mapper.readerFor(User.class) .readValues(new File(big.json))) { while (iterator.hasNext()) { User user iterator.next(); // 逐条处理 } }这个在数据迁移、批量导出场景特别有用。我做过一个百万级数据的导出用writeValueAsString直接OOM改成流式之后内存稳定在几十MB。7. 常见问题排查速查表7.1 高频异常和解决思路异常信息原因解决方式UnrecognizedPropertyExceptionJSON有POJO没有的字段加JsonIgnoreProperties(ignoreUnknowntrue)或全局关FAIL_ON_UNKNOWN_PROPERTIESInvalidFormatException字段类型或格式不匹配检查日期格式、数字类型用JsonFormat对齐Infinite recursion循环引用用JsonBackReference或JsonIdentityInfoNo serializer found空对象或没有getter关FAIL_ON_EMPTY_BEANS补getterInvalidDefinitionException缺JavaTimeModule引入jackson-datatype-jsr310并注册MismatchedInputExceptionJSON结构对不上检查是否数组传了对象或反之UnrecognizedPropertyException是最常见的尤其是对接第三方接口时。错误信息里会明确告诉你哪个字段不认识照着加忽略配置就行。MismatchedInputException通常是前端传参格式错了比如该传数组传了对象错误信息里会带上期望类型和实际类型对着看就能定位。7.2 几个容易踩的坑第一个坑静态内部类和内部类的区别。非静态内部类反序列化时会因为缺少外部类实例而失败报InvalidDefinitionException。解决办法是把DTO改成静态内部类或者独立类。这个坑我在写单元测试时踩过当时DTO定义在测试类里没加static反序列化一直失败查了半天才发现。第二个坑Lombok和Jackson的配合。Lombok生成的getter/setter命名有时不符合Jackson的推断规则比如isSuccess()这种布尔字段Jackson可能推断成success也可能推断成isSuccess取决于版本和配置。稳妥的做法是显式加JsonProperty别依赖自动推断。第三个坑泛型嵌套太深。MapString, ListMapString, User这种类型用TypeReference写起来很痛苦而且容易写错。这种场景建议定义明确的DTO类别用嵌套泛型硬扛可读性和可维护性都差。第四个坑序列化结果字段顺序。Jackson默认按字段声明顺序输出但经过混淆或者继承之后顺序可能变。如果下游依赖字段顺序比如做签名要显式用JsonPropertyOrder指定顺序别赌默认行为。7.3 调试技巧怎么快速定位序列化问题排查序列化问题我常用的几个手段一是打开SerializationFeature.INDENT_OUTPUT输出格式化后的JSON肉眼检查结构mapper.enable(SerializationFeature.INDENT_OUTPUT);二是用mapper.writeValueAsString之前先convertValue成Map看看中间结果MapString, Object debug mapper.convertValue(obj, Map.class); System.out.println(debug);这样能看出是序列化阶段丢的字段还是对象本身就没值。三是自定义序列化器里打日志确认序列化器有没有被调用。有时候注解写错了包路径序列化器根本没生效打日志一看就知道。四是版本冲突排查用mvn dependency:tree | grep jackson看依赖树确认core、databind、annotations版本一致。版本不一致导致的问题最隐蔽表现五花八门但排查方法最简单先看依赖树。8. 和Spring Boot集成时的注意事项8.1 自定义ObjectMapper的正确姿势Spring Boot自动配置了一个ObjectMapper你如果想定制不要直接new一个替换而是通过Jackson2ObjectMapperBuilderCustomizer或者直接定义Bean覆盖Bean public Jackson2ObjectMapperBuilderCustomizer jacksonCustomizer() { return builder - { builder.serializationInclusion(JsonInclude.Include.NON_NULL); builder.featuresToDisable( DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES); builder.modules(new JavaTimeModule()); }; }用Customizer的好处是保留Spring的默认配置只改你需要的部分。直接定义Bean ObjectMapper会完全替换默认的Spring自带的一些配置比如ParameterNamesModule就没了可能导致ConstructorProperties相关的反序列化失效。8.2 请求响应和消息队列的配置隔离Spring MVC的HTTP序列化和消息队列比如Kafka、RabbitMQ的序列化通常需要不同的配置。HTTP层可能要求日期格式友好、忽略null消息队列层可能要求全字段输出、用时间戳。这时候不要共用一个ObjectMapper给消息队列单独配一个Bean(mqObjectMapper) public ObjectMapper mqObjectMapper() { ObjectMapper mapper new ObjectMapper(); mapper.registerModule(new JavaTimeModule()); mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); return mapper; }然后在消息转换器里指定用这个bean。共用配置的后果是改了一边影响另一边排查起来很痛苦。我见过一个项目HTTP接口和Kafka消息共用一个mapper后来产品要求接口日期格式改成yyyy年MM月dd日结果Kafka消息的日期格式也跟着变了下游消费方直接解析失败。8.3 全局异常处理里的序列化问题Spring的全局异常处理器返回错误信息时也会走序列化如果异常对象里有循环引用或者不可序列化的字段会导致异常处理本身失败最终返回一个默认的500错误页把真正的错误信息吞掉。解决办法是异常处理器返回专门的错误DTO别直接返回异常对象ExceptionHandler(Exception.class) public ResponseEntityErrorDTO handle(Exception e) { ErrorDTO error new ErrorDTO(); error.setCode(500); error.setMessage(e.getMessage()); return ResponseEntity.status(500).body(error); }ErrorDTO里只放字符串和基本类型不放异常堆栈和复杂对象保证一定能序列化成功。这个细节在线上排查问题时特别重要异常处理器自己挂了你就失去了所有错误上下文。9. 一些实战中的经验补充9.1 序列化兼容性的设计原则微服务之间用JSON通信字段增减是常态。设计DTO时要考虑向前兼容新增字段给默认值别让老版本反序列化失败删除字段先标记Deprecated观察一段时间确认没人用再删字段改名用JsonAlias过渡别直接改。这些原则说起来简单但实际项目里经常有人直接改字段名导致上下游联调时各种UnrecognizedPropertyException。另一个原则是不要序列化实体类。实体类里有懒加载代理、双向关联、数据库特有字段直接序列化问题一堆。用DTO做传输层实体和DTO之间用convertValue或者手动映射转换虽然多写一点代码但省去了后面无数的坑。9.2 测试里怎么验证序列化行为序列化配置改完之后一定要写测试验证。我通常写两类测试一类是快照测试把序列化结果和预期JSON字符串比对另一类是往返测试序列化再反序列化断言对象相等。Test public void testSerializeDeserialize() throws Exception { User user new User(); user.setName(张三); user.setCreateTime(LocalDateTime.of(2024, 1, 15, 10, 30)); String json mapper.writeValueAsString(user); User parsed mapper.readValue(json, User.class); assertEquals(user.getName(), parsed.getName()); assertEquals(user.getCreateTime(), parsed.getCreateTime()); }往返测试能发现大部分配置问题尤其是日期格式和时区。快照测试则能防止无意中改了序列化行为。测试里的ObjectMapper要和生产环境用同一份配置别在测试里new一个默认的那样测了等于没测。9.3 版本升级的注意事项Jackson从2.x升级到2.15以上时有些废弃的配置方法被移除了比如configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false)还能用但enable和disable的语义在某些特性上有调整。升级前先看release notes重点看MapperFeature和SerializationFeature的变更。另外jackson-datatype-jsr310的版本要跟着databind一起升别只升一个。升级后跑一遍全量测试重点验证日期、枚举、泛型这三块它们是版本变更影响最大的地方。我经历过一次升级枚举的默认序列化行为从name变成了toString而项目里有个枚举重写了toString返回中文描述结果接口返回的枚举值全变了前端直接懵了。后来加了WRITE_ENUMS_USING_TO_STRING的显式配置才稳定下来。9.4 安全相关的配置反序列化是安全敏感操作尤其是接收外部输入时。Jackson默认会实例化JSON里指定的类型如果开了enableDefaultTyping老版本或者用了不安全的JsonTypeInfo配置可能被利用来实例化恶意类。新版本默认关闭了这些危险特性但如果你从老项目迁移过来检查一下有没有残留的enableDefaultTyping调用有的话删掉。另外反序列化大JSON时要限制深度和大小防止恶意构造的超深嵌套导致栈溢出。StreamReadConstraints可以配置最大嵌套深度、最大字符串长度这些限制mapper.getFactory().setStreamReadConstraints( StreamReadConstraints.builder() .maxNestingDepth(1000) .maxStringLength(10_000_000) .build());这些限制在接收外部请求的场景下建议都配上默认值虽然有一定保护但按业务实际情况收紧更安全。9.5 一个完整的生产级配置参考最后给一份我目前在用的生产配置涵盖了前面提到的各个点Configuration public class JacksonConfig { Bean public Jackson2ObjectMapperBuilderCustomizer customizer() { return builder - { // 基础配置 builder.serializationInclusion(JsonInclude.Include.NON_NULL); builder.featuresToDisable( DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, SerializationFeature.FAIL_ON_EMPTY_BEANS, SerializationFeature.WRITE_DATES_AS_TIMESTAMPS ); builder.featuresToEnable( SerializationFeature.WRITE_ENUMS_USING_TO_STRING ); // 日期时间 DateTimeFormatter formatter DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); JavaTimeModule timeModule new JavaTimeModule(); timeModule.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(formatter)); timeModule.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer(formatter)); builder.modules(timeModule); // 时区 builder.timeZone(TimeZone.getTimeZone(Asia/Shanghai)); }; } }这份配置在多个项目里跑过覆盖了大部分业务场景。当然具体项目还要按需调整比如有的项目要求null字段也输出那就把NON_NULL去掉有的项目枚举要输出code那就得自定义枚举序列化器。配置没有银弹理解每个开关的作用按自己的场景组合才是正道。我在实际使用中最大的体会是ObjectMapper的坑大多不在API本身而在配置的组合和版本的一致性上。把配置集中管理、写测试兜底、升级时看变更日志这三件事做到位序列化这块基本就不会再出幺蛾子。另外遇到序列化问题别急着搜答案先把异常信息完整读一遍Jackson的异常信息其实写得很清楚大部分时候答案就在里面。
做后端开发这些年序列化这块踩过的坑真不少。早期用原生手写拼JSON字段一多就乱套后来换成Jackson一开始也只是停留在writeValueAsString和readValue两个方法上直到项目里遇到泛型反序列化、日期格式错乱、循环引用栈溢出、字段名对不上这些破事才被逼着把ObjectMapper从头到尾啃了一遍。这篇内容就是把这些年关于ObjectMapper的使用经验系统整理出来从配置、核心API、泛型处理、日期时间、循环引用、自定义序列化器到性能优化和常见问题排查全部讲透。不管你是刚接触Jackson的新手还是已经用过一段时间但总觉得配置不够顺手的老手应该都能从里面找到能直接抄作业的东西。核心关键词ObjectMapper会贯穿全文我会尽量用大白话加实际代码把每个点讲清楚让你看完就能在自己的项目里落地。1. 先搞清楚ObjectMapper到底是个什么东西1.1 它在整个序列化体系里的位置ObjectMapper是Jackson数据绑定模块的核心类负责Java对象和JSON字符串之间的双向转换。你可以把它理解成一个翻译官Java对象是中文JSON是英文ObjectMapper就是那个既懂中文又懂英文、还能按你的要求调整翻译风格的人。它内部依赖JsonParser和JsonGenerator完成底层的读写同时通过SerializerProvider和DeserializerProvider管理各种类型的序列化器和反序列化器。很多人以为ObjectMapper只是个工具类随便new一个就能用这个认知是第一个坑。ObjectMapper本身是线程安全的前提是你配置好之后不再修改它。官方文档明确说过一旦配置完成它可以被多个线程共享。但如果你在运行时动态调用setSerializationInclusion、configure这类方法就会破坏线程安全性。所以正确的做法是在应用启动时完成所有配置然后把它作为单例注入到需要的地方而不是每次用的时候都new一个。从依赖关系上看ObjectMapper属于jackson-databind模块它又依赖jackson-core和jackson-annotations。这三个包版本必须保持一致否则会出现NoSuchMethodError或者行为不一致的问题。我见过有项目里core是2.9、databind是2.13跑起来序列化结果莫名其妙丢字段排查了大半天才发现是版本冲突。所以第一件事先把版本对齐。1.2 为什么不用Gson或者Fastjson这个问题被问过很多次。客观说Gson轻量、API简单Fastjson在国内用得多、性能也不错但ObjectMapper的优势在于生态完整和扩展性强。Spring Boot默认集成JacksonSpring MVC的RequestBody和ResponseBody底层就是ObjectMapper在干活你用Spring就绕不开它。另外Jackson的注解体系非常丰富JsonProperty、JsonIgnore、JsonFormat、JsonSerialize这些注解能覆盖绝大多数定制需求自定义序列化器的接入也很顺滑。性能方面Jackson在流式处理和大对象场景下表现稳定配合ObjectReader和ObjectWriter复用可以进一步减少开销。Fastjson历史上出过一些安全漏洞Gson在复杂泛型处理上不如Jackson灵活。当然这不是说其他库不好而是说在Spring生态里ObjectMapper是阻力最小的选择。你如果项目里已经用了别的库没必要为了换而换但如果新项目跟着Spring走基本不会错。1.3 一个最小可用的配置模板先给一个我平时用的基础配置后面所有例子都基于这个模板展开ObjectMapper mapper new ObjectMapper(); // 反序列化时忽略JSON中多出来的字段避免上游加字段导致下游报错 mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); // 序列化时忽略值为null的字段 mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL); // 日期统一用ISO-8601格式不用时间戳 mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); // 枚举按名字序列化而不是序号 mapper.configure(SerializationFeature.WRITE_ENUMS_USING_TO_STRING, true);这几行配置解决了我遇到的大部分默认行为不符合预期的问题。FAIL_ON_UNKNOWN_PROPERTIES设为false尤其重要微服务之间字段增减很常见不关掉这个开关上游加个字段下游就炸了。NON_NULL能显著减小传输体积但要注意它只影响序列化反序列化时null字段照样能正常处理。2. 核心API逐个拆解别只会writeValueAsString2.1 序列化的几种姿势和适用场景ObjectMapper的序列化方法看着多其实按输出目标分三类转字符串、转字节数组、写文件或输出流。// 转字符串最常用 String json mapper.writeValueAsString(user); // 转字节数组适合网络传输或存Redis byte[] bytes mapper.writeValueAsBytes(user); // 写文件 mapper.writeValue(new File(user.json), user); // 写输出流适合Web响应 mapper.writeValue(response.getOutputStream(), user);选哪个取决于你的下游。转字符串最直观但字符串在内存里占的空间是字节的两倍左右大对象频繁序列化时用writeValueAsBytes更省内存。写文件的方式适合做数据导出但要注意它会覆盖原文件追加场景得自己控制流。还有一个容易被忽略的点writeValueAsString在遇到无法序列化的对象时会抛JsonProcessingException这是受检异常必须处理。很多人直接throws Exception往上抛结果在Controller层被全局异常处理器吞掉返回给前端一个500日志里却看不出具体是哪个字段出的问题。我的做法是捕获后把对象类型和字段信息拼进异常消息里排查时能省很多时间。2.2 反序列化的三种入口和泛型处理反序列化比序列化复杂因为Java的类型擦除机制导致泛型信息在运行时丢失。readValue(String, Class)只能处理简单类型遇到ListUser、MapString, ListUser这种嵌套泛型就抓瞎了。这时候要用TypeReference// 错误示范这样拿到的是ListLinkedHashMap不是ListUser ListUser wrong mapper.readValue(json, List.class); // 正确姿势用TypeReference保留泛型信息 ListUser users mapper.readValue(json, new TypeReferenceListUser() {}); // 嵌套泛型也没问题 MapString, ListUser map mapper.readValue(json, new TypeReferenceMapString, ListUser() {});TypeReference的原理是通过匿名子类在编译期把泛型信息写进class文件的签名里运行时通过反射拿到。注意它必须写成匿名内部类的形式写成new TypeReferenceListUser()后面不带花括号是不行的那样拿不到泛型参数。除了TypeReference还可以用JavaType适合需要动态构造类型的场景JavaType listType mapper.getTypeFactory() .constructCollectionType(List.class, User.class); ListUser users mapper.readValue(json, listType);JavaType的好处是可以在运行时根据配置动态拼类型比如从数据库读出来一个类型名字符串再反射构造对应的JavaType。TypeReference是编译期确定的JavaType是运行期构造的两者按需选用。2.3 树模型JsonNode的灵活读取有时候你不需要把JSON映射成具体对象只是想读其中几个字段或者JSON结构不固定这时候用树模型JsonNode最合适JsonNode root mapper.readTree(json); String name root.get(name).asText(); int age root.get(age).asInt(); // 遍历数组 JsonNode items root.get(items); for (JsonNode item : items) { System.out.println(item.get(id).asLong()); }JsonNode的好处是不需要预先定义类适合处理半结构化数据。但它也有代价每次get都是哈希查找大文档频繁读取性能不如直接映射成POJO。我的经验是字段少于五个、或者结构经常变的场景用JsonNode结构稳定的业务对象老老实实定义POJO。JsonNode还有几个实用方法path()和get()的区别在于path在字段不存在时返回MissingNode而不是null可以链式调用不抛NPEhas()判断字段是否存在isArray()、isObject()判断节点类型。这些在写防御性代码时很有用。2.4 对象转换convertValue的妙用convertValue是个被低估的方法它能把一个对象转成另一种类型中间走的是序列化加反序列化的流程// 把Map转成POJO MapString, Object map new HashMap(); map.put(name, 张三); map.put(age, 25); User user mapper.convertValue(map, User.class); // 把POJO转成Map MapString, Object result mapper.convertValue(user, Map.class);这个在对接第三方接口时特别有用对方返回的JSON你先用Map接住做一轮字段清洗和转换再convertValue成自己的业务对象。比直接映射成POJO再改字段要灵活。注意convertValue底层也是走完整的序列化反序列化性能不如直接映射高频调用场景要谨慎。3. 注解体系把定制化需求交给声明式配置3.1 字段级别的常用注解Jackson的注解是它最强大的部分大部分定制需求不用写代码加个注解就搞定。最常用的几个注解作用典型场景JsonProperty指定JSON字段名前后端字段命名风格不一致JsonIgnore序列化和反序列化都忽略密码、内部状态字段JsonIgnoreProperties类级别忽略多个字段忽略上游多余字段JsonFormat格式化日期、数字日期格式、时区JsonAlias反序列化时接受多个别名兼容上游字段改名JsonProperty(access)控制读写权限只读或只写字段JsonProperty最典型的用法是处理下划线和驼峰不一致的问题。比如数据库字段是user_nameJava属性是userName加个JsonProperty(user_name)就对齐了。JsonAlias则是反序列化时的多别名支持上游从user_name改成username你不想改代码加个别名就能同时兼容两种。JsonIgnore和JsonProperty(access Access.WRITE_ONLY)的区别要分清前者序列化和反序列化都忽略后者只在序列化时忽略、反序列化时仍然接收。密码字段通常用WRITE_ONLY前端传密码能接收返回用户信息时不带密码。3.2 类级别的注解和全局配置的优先级类级别注解里JsonIgnoreProperties(ignoreUnknown true)用得最多它等价于全局的FAIL_ON_UNKNOWN_PROPERTIESfalse但只对当前类生效。如果你的项目里大部分类都需要忽略未知字段用全局配置更省事如果只有个别类需要用类注解更精确。JsonNaming可以批量指定命名策略比如JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class)让整个类的字段都按蛇形命名序列化不用每个字段加JsonProperty。这个在对接Python或Go服务时特别方便因为那些语言习惯用下划线。注解和全局配置的优先级是注解优先于全局配置。比如全局设了NON_NULL但某个字段你想让它即使为null也输出加个JsonInclude(JsonInclude.Include.ALWAYS)就能覆盖。这个优先级规则要记牢排查序列化结果不符合预期时先看有没有注解覆盖了全局配置。3.3 自定义序列化器和反序列化器注解搞不定的场景就得上自定义序列化器。比如枚举你想序列化成自定义的code而不是name或者某个字段需要加密后输出public class SensitiveSerializer extends JsonSerializerString { Override public void serialize(String value, JsonGenerator gen, SerializerProvider provider) throws IOException { // 手机号脱敏138****1234 if (value ! null value.length() 11) { gen.writeString(value.substring(0, 3) **** value.substring(7)); } else { gen.writeString(value); } } } // 在字段上使用 public class User { JsonSerialize(using SensitiveSerializer.class) private String phone; }自定义反序列化器则是JsonDeserializer重写deserialize方法。注意反序列化器里要处理null和空字符串的情况否则容易抛NPE。另外自定义序列化器注册到ObjectMapper上有两种方式字段上打注解或者用SimpleModule全局注册。全局注册适合某个类型在所有地方都要特殊处理的情况比如统一处理所有枚举。SimpleModule module new SimpleModule(); module.addSerializer(MyEnum.class, new MyEnumSerializer()); mapper.registerModule(module);用SimpleModule注册时要注意注册顺序后注册的会覆盖先注册的。如果同时用了多个模块建议在启动时打印一下已注册的模块列表避免互相覆盖导致行为诡异。4. 日期时间处理最容易出问题的重灾区4.1 默认行为为什么坑ObjectMapper对java.util.Date的默认序列化是输出时间戳毫秒数对LocalDateTime默认输出数组形式[2024,1,15,10,30,0]。这两个默认行为几乎没人满意时间戳前端要自己转数组形式更是反人类。所以日期处理几乎是每个项目都要配置的。// 关闭时间戳输出 mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); // 注册Java 8时间模块 mapper.registerModule(new JavaTimeModule());JavaTimeModule是jackson-datatype-jsr310包提供的专门处理LocalDateTime、LocalDate、Instant这些Java 8时间类型。不注册这个模块直接序列化LocalDateTime会抛InvalidDefinitionException。这个包要单独引入依赖很多人只引了jackson-databind结果一用LocalDateTime就报错还以为是配置问题。4.2 全局日期格式和时区配置注册模块之后还要统一格式和时区SimpleModule module new JavaTimeModule(); // 自定义LocalDateTime的序列化和反序列化格式 DateTimeFormatter formatter DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); module.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(formatter)); module.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer(formatter)); mapper.registerModule(module); // 设置全局时区 mapper.setTimeZone(TimeZone.getTimeZone(Asia/Shanghai));时区这个点必须强调。服务器默认时区可能是UTC数据库存的是东八区时间序列化出来差8小时前端展示就错了。setTimeZone只影响Date和CalendarLocalDateTime本身不带时区信息所以格式化和时区要分开处理。我的建议是内部统一用LocalDateTime存不带时区的时间跨时区传输用Instant或带偏移量的OffsetDateTime展示层再按用户时区转换。4.3 字段级日期格式覆盖全局格式不一定满足所有字段比如大部分字段要yyyy-MM-dd HH:mm:ss但某个字段只要日期yyyy-MM-dd这时候用JsonFormat覆盖public class Order { JsonFormat(pattern yyyy-MM-dd HH:mm:ss, timezone GMT8) private LocalDateTime createTime; JsonFormat(pattern yyyy-MM-dd) private LocalDate deliveryDate; }JsonFormat的timezone属性对Date类型有效对LocalDateTime无效因为后者不带时区。这个细节很多人搞混配了timezone发现没生效其实是类型选错了。另外反序列化时如果前端传的格式和pattern对不上会抛InvalidFormatException错误信息里会带上期望格式和实际值排查时直接看这个信息就行。5. 循环引用和复杂对象图处理5.1 循环引用是怎么产生的双向关联的实体最容易出循环引用。比如User有ListOrderOrder又有个User引用序列化User时递归到Order又回到User无限递归直到栈溢出。错误信息通常是StackOverflowError或者JsonMappingException: Infinite recursion。这个问题在JPA/Hibernate项目里特别常见因为实体之间经常配双向关联。解决办法有三种各有适用场景。5.2 三种解决方案对比第一种是JsonIgnore在其中一个方向上忽略public class Order { JsonIgnore private User user; }简单粗暴但缺点是反序列化时这个字段也读不进来。如果只是序列化时想断开循环反序列化还需要这个字段就不能用这个。第二种是JsonManagedReference和JsonBackReference配对使用public class User { JsonManagedReference private ListOrder orders; } public class Order { JsonBackReference private User user; }JsonManagedReference标记的字段正常序列化JsonBackReference标记的字段序列化时被忽略但反序列化时能正常读入。这个方案适合父子关系明确的场景缺点是只能处理一对配对多个双向关联时容易配错。第三种是JsonIdentityInfo给每个对象加个标识重复出现时只输出标识JsonIdentityInfo(generator ObjectIdGenerators.PropertyGenerator.class, property id) public class User { private Long id; private ListOrder orders; }这个方案适合对象图复杂、多处引用的场景序列化结果里第二次出现的对象只输出id。缺点是前端解析时要自己处理引用关系而且如果对象没有唯一id字段就用不了。我的经验是简单的父子关系用JsonBackReference复杂对象图用JsonIdentityInfo临时应急用JsonIgnore。但根本上DTO和实体分离才是治本之道实体负责持久化DTO负责传输DTO里只放需要的字段从源头上避免循环引用。6. 性能优化别让序列化成为瓶颈6.1 ObjectMapper复用和ObjectWriter前面说过ObjectMapper是线程安全的配置好后可以全局复用。但每次调用writeValueAsString时它内部还是会做一些查找序列化器的开销。高频场景可以用ObjectWriter和ObjectReader预编译// 预编译writer适合固定类型的频繁序列化 ObjectWriter writer mapper.writerFor(User.class); String json writer.writeValueAsString(user); // 预编译reader ObjectReader reader mapper.readerFor(User.class); User user reader.readValue(json);ObjectWriter和ObjectReader是不可变对象创建后可以缓存复用内部已经绑定了类型信息省去了每次查找的开销。在QPS高的接口里这个优化能带来10%到20%的提升具体取决于对象复杂度。6.2 关闭不必要的特性ObjectMapper默认开启了一些你可能不需要的特性关掉能省点性能// 关闭自动检测getter显式用JsonProperty标注 mapper.disable(MapperFeature.AUTO_DETECT_GETTERS); // 关闭FAIL_ON_EMPTY_BEANS避免空对象报错 mapper.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS);AUTO_DETECT_GETTERS关掉后只有加了JsonProperty的字段才会被序列化好处是序列化范围可控坏处是每个字段都要加注解维护成本高。这个看团队习惯字段少的DTO可以关字段多的还是开着省事。FAIL_ON_EMPTY_BEANS建议关掉因为有些代理对象或者空集合序列化时会触发这个检查报错信息还不直观。关掉之后空对象序列化成{}比抛异常友好。6.3 大对象和流式处理处理超大JSON比如几百MB的导出文件时不要用writeValueAsString一次性加载到内存用流式APItry (JsonGenerator generator mapper.getFactory() .createGenerator(new FileOutputStream(big.json))) { generator.writeStartArray(); for (User user : userList) { mapper.writeValue(generator, user); } generator.writeEndArray(); }流式写入边读边写内存占用恒定。读取大文件同理用MappingIterator逐条读取try (MappingIteratorUser iterator mapper.readerFor(User.class) .readValues(new File(big.json))) { while (iterator.hasNext()) { User user iterator.next(); // 逐条处理 } }这个在数据迁移、批量导出场景特别有用。我做过一个百万级数据的导出用writeValueAsString直接OOM改成流式之后内存稳定在几十MB。7. 常见问题排查速查表7.1 高频异常和解决思路异常信息原因解决方式UnrecognizedPropertyExceptionJSON有POJO没有的字段加JsonIgnoreProperties(ignoreUnknowntrue)或全局关FAIL_ON_UNKNOWN_PROPERTIESInvalidFormatException字段类型或格式不匹配检查日期格式、数字类型用JsonFormat对齐Infinite recursion循环引用用JsonBackReference或JsonIdentityInfoNo serializer found空对象或没有getter关FAIL_ON_EMPTY_BEANS补getterInvalidDefinitionException缺JavaTimeModule引入jackson-datatype-jsr310并注册MismatchedInputExceptionJSON结构对不上检查是否数组传了对象或反之UnrecognizedPropertyException是最常见的尤其是对接第三方接口时。错误信息里会明确告诉你哪个字段不认识照着加忽略配置就行。MismatchedInputException通常是前端传参格式错了比如该传数组传了对象错误信息里会带上期望类型和实际类型对着看就能定位。7.2 几个容易踩的坑第一个坑静态内部类和内部类的区别。非静态内部类反序列化时会因为缺少外部类实例而失败报InvalidDefinitionException。解决办法是把DTO改成静态内部类或者独立类。这个坑我在写单元测试时踩过当时DTO定义在测试类里没加static反序列化一直失败查了半天才发现。第二个坑Lombok和Jackson的配合。Lombok生成的getter/setter命名有时不符合Jackson的推断规则比如isSuccess()这种布尔字段Jackson可能推断成success也可能推断成isSuccess取决于版本和配置。稳妥的做法是显式加JsonProperty别依赖自动推断。第三个坑泛型嵌套太深。MapString, ListMapString, User这种类型用TypeReference写起来很痛苦而且容易写错。这种场景建议定义明确的DTO类别用嵌套泛型硬扛可读性和可维护性都差。第四个坑序列化结果字段顺序。Jackson默认按字段声明顺序输出但经过混淆或者继承之后顺序可能变。如果下游依赖字段顺序比如做签名要显式用JsonPropertyOrder指定顺序别赌默认行为。7.3 调试技巧怎么快速定位序列化问题排查序列化问题我常用的几个手段一是打开SerializationFeature.INDENT_OUTPUT输出格式化后的JSON肉眼检查结构mapper.enable(SerializationFeature.INDENT_OUTPUT);二是用mapper.writeValueAsString之前先convertValue成Map看看中间结果MapString, Object debug mapper.convertValue(obj, Map.class); System.out.println(debug);这样能看出是序列化阶段丢的字段还是对象本身就没值。三是自定义序列化器里打日志确认序列化器有没有被调用。有时候注解写错了包路径序列化器根本没生效打日志一看就知道。四是版本冲突排查用mvn dependency:tree | grep jackson看依赖树确认core、databind、annotations版本一致。版本不一致导致的问题最隐蔽表现五花八门但排查方法最简单先看依赖树。8. 和Spring Boot集成时的注意事项8.1 自定义ObjectMapper的正确姿势Spring Boot自动配置了一个ObjectMapper你如果想定制不要直接new一个替换而是通过Jackson2ObjectMapperBuilderCustomizer或者直接定义Bean覆盖Bean public Jackson2ObjectMapperBuilderCustomizer jacksonCustomizer() { return builder - { builder.serializationInclusion(JsonInclude.Include.NON_NULL); builder.featuresToDisable( DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES); builder.modules(new JavaTimeModule()); }; }用Customizer的好处是保留Spring的默认配置只改你需要的部分。直接定义Bean ObjectMapper会完全替换默认的Spring自带的一些配置比如ParameterNamesModule就没了可能导致ConstructorProperties相关的反序列化失效。8.2 请求响应和消息队列的配置隔离Spring MVC的HTTP序列化和消息队列比如Kafka、RabbitMQ的序列化通常需要不同的配置。HTTP层可能要求日期格式友好、忽略null消息队列层可能要求全字段输出、用时间戳。这时候不要共用一个ObjectMapper给消息队列单独配一个Bean(mqObjectMapper) public ObjectMapper mqObjectMapper() { ObjectMapper mapper new ObjectMapper(); mapper.registerModule(new JavaTimeModule()); mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); return mapper; }然后在消息转换器里指定用这个bean。共用配置的后果是改了一边影响另一边排查起来很痛苦。我见过一个项目HTTP接口和Kafka消息共用一个mapper后来产品要求接口日期格式改成yyyy年MM月dd日结果Kafka消息的日期格式也跟着变了下游消费方直接解析失败。8.3 全局异常处理里的序列化问题Spring的全局异常处理器返回错误信息时也会走序列化如果异常对象里有循环引用或者不可序列化的字段会导致异常处理本身失败最终返回一个默认的500错误页把真正的错误信息吞掉。解决办法是异常处理器返回专门的错误DTO别直接返回异常对象ExceptionHandler(Exception.class) public ResponseEntityErrorDTO handle(Exception e) { ErrorDTO error new ErrorDTO(); error.setCode(500); error.setMessage(e.getMessage()); return ResponseEntity.status(500).body(error); }ErrorDTO里只放字符串和基本类型不放异常堆栈和复杂对象保证一定能序列化成功。这个细节在线上排查问题时特别重要异常处理器自己挂了你就失去了所有错误上下文。9. 一些实战中的经验补充9.1 序列化兼容性的设计原则微服务之间用JSON通信字段增减是常态。设计DTO时要考虑向前兼容新增字段给默认值别让老版本反序列化失败删除字段先标记Deprecated观察一段时间确认没人用再删字段改名用JsonAlias过渡别直接改。这些原则说起来简单但实际项目里经常有人直接改字段名导致上下游联调时各种UnrecognizedPropertyException。另一个原则是不要序列化实体类。实体类里有懒加载代理、双向关联、数据库特有字段直接序列化问题一堆。用DTO做传输层实体和DTO之间用convertValue或者手动映射转换虽然多写一点代码但省去了后面无数的坑。9.2 测试里怎么验证序列化行为序列化配置改完之后一定要写测试验证。我通常写两类测试一类是快照测试把序列化结果和预期JSON字符串比对另一类是往返测试序列化再反序列化断言对象相等。Test public void testSerializeDeserialize() throws Exception { User user new User(); user.setName(张三); user.setCreateTime(LocalDateTime.of(2024, 1, 15, 10, 30)); String json mapper.writeValueAsString(user); User parsed mapper.readValue(json, User.class); assertEquals(user.getName(), parsed.getName()); assertEquals(user.getCreateTime(), parsed.getCreateTime()); }往返测试能发现大部分配置问题尤其是日期格式和时区。快照测试则能防止无意中改了序列化行为。测试里的ObjectMapper要和生产环境用同一份配置别在测试里new一个默认的那样测了等于没测。9.3 版本升级的注意事项Jackson从2.x升级到2.15以上时有些废弃的配置方法被移除了比如configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false)还能用但enable和disable的语义在某些特性上有调整。升级前先看release notes重点看MapperFeature和SerializationFeature的变更。另外jackson-datatype-jsr310的版本要跟着databind一起升别只升一个。升级后跑一遍全量测试重点验证日期、枚举、泛型这三块它们是版本变更影响最大的地方。我经历过一次升级枚举的默认序列化行为从name变成了toString而项目里有个枚举重写了toString返回中文描述结果接口返回的枚举值全变了前端直接懵了。后来加了WRITE_ENUMS_USING_TO_STRING的显式配置才稳定下来。9.4 安全相关的配置反序列化是安全敏感操作尤其是接收外部输入时。Jackson默认会实例化JSON里指定的类型如果开了enableDefaultTyping老版本或者用了不安全的JsonTypeInfo配置可能被利用来实例化恶意类。新版本默认关闭了这些危险特性但如果你从老项目迁移过来检查一下有没有残留的enableDefaultTyping调用有的话删掉。另外反序列化大JSON时要限制深度和大小防止恶意构造的超深嵌套导致栈溢出。StreamReadConstraints可以配置最大嵌套深度、最大字符串长度这些限制mapper.getFactory().setStreamReadConstraints( StreamReadConstraints.builder() .maxNestingDepth(1000) .maxStringLength(10_000_000) .build());这些限制在接收外部请求的场景下建议都配上默认值虽然有一定保护但按业务实际情况收紧更安全。9.5 一个完整的生产级配置参考最后给一份我目前在用的生产配置涵盖了前面提到的各个点Configuration public class JacksonConfig { Bean public Jackson2ObjectMapperBuilderCustomizer customizer() { return builder - { // 基础配置 builder.serializationInclusion(JsonInclude.Include.NON_NULL); builder.featuresToDisable( DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, SerializationFeature.FAIL_ON_EMPTY_BEANS, SerializationFeature.WRITE_DATES_AS_TIMESTAMPS ); builder.featuresToEnable( SerializationFeature.WRITE_ENUMS_USING_TO_STRING ); // 日期时间 DateTimeFormatter formatter DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); JavaTimeModule timeModule new JavaTimeModule(); timeModule.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(formatter)); timeModule.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer(formatter)); builder.modules(timeModule); // 时区 builder.timeZone(TimeZone.getTimeZone(Asia/Shanghai)); }; } }这份配置在多个项目里跑过覆盖了大部分业务场景。当然具体项目还要按需调整比如有的项目要求null字段也输出那就把NON_NULL去掉有的项目枚举要输出code那就得自定义枚举序列化器。配置没有银弹理解每个开关的作用按自己的场景组合才是正道。我在实际使用中最大的体会是ObjectMapper的坑大多不在API本身而在配置的组合和版本的一致性上。把配置集中管理、写测试兜底、升级时看变更日志这三件事做到位序列化这块基本就不会再出幺蛾子。另外遇到序列化问题别急着搜答案先把异常信息完整读一遍Jackson的异常信息其实写得很清楚大部分时候答案就在里面。
