1. 为什么你写的JSON总是“不对劲”Spring Boot里Jackson不是配个EnableWebMvc就完事的我刚接手一个老项目时前端同事发来截图后端返回的日期是2024-07-15T08:30:45.1230000而他们要的是2024-07-15 08:30:45另一个接口返回的枚举字段明明是{status:PENDING}前端却收到{status:1}还有更离谱的——空字符串被序列化成null导致前端表单校验直接崩掉。排查三天最后发现只是Jackson没配对时区、没开WRITE_ENUMS_USING_TO_STRING、没关SERIALIZE_NULLS。这根本不是代码逻辑问题而是Jackson配置的“默认陷阱”。Spring Boot确实自动装配了ObjectMapper但它给的是一套面向通用HTTP协议的保守配置不是面向你业务场景的生产级配置。你写的每个RestController方法背后都有一台精密但默认“出厂设置”的JSON引擎在默默工作。它不报错但会悄悄把你的业务语义扭曲成标准格式。比如LocalDateTime默认序列化成ISO-8601字符串可你数据库里存的是yyyy-MM-dd HH:mm:ss比如BigDecimal默认保留全部小数位但前端展示只需要两位再比如null字段默认被忽略可你协议要求必须返回price:null来标识未定价。这些都不是Bug是配置缺失导致的语义失真。真正的问题在于很多人以为加了ResponseBody就万事大吉却不知道Jackson才是那个决定“数据长什么样”的幕后操盘手。它不像MySQL连接池那样会抛ConnectionTimeoutException给你明确警告而是用静默的方式把你的业务意图悄悄替换成它认为“正确”的样子。所以这篇内容不是讲怎么“用Jackson”而是带你亲手拆开这个默认引擎换上符合你业务节奏的活塞、校准喷油嘴、调好点火正时——让JSON输出真正成为你业务语言的忠实翻译官而不是自作主张的编辑。2. Jackson配置的三层结构从Spring Boot自动装配到业务语义落地2.1 Spring Boot的自动装配机制它到底给你装了什么Spring Boot的spring-boot-starter-web依赖里HttpMessageConverters的自动配置是核心。当你引入该starterSpring Boot会通过WebMvcAutoConfiguration类注册一系列HttpMessageConverter其中最关键的是MappingJackson2HttpMessageConverter。这个Converter内部持有一个ObjectMapper实例而这个实例的创建过程就是所有配置的起点。它不是凭空生成的而是由Jackson2ObjectMapperBuilder构建器驱动。这个Builder会按顺序加载三类配置源第一层是框架默认值ObjectMapper的原始构造函数设定的基础行为比如DEFAULT_DATE_FORMAT是new SimpleDateFormat(yyyy-MM-dd HH:mm:ss.SSS)但注意——这个默认值在Spring Boot中实际并未启用因为后续会被覆盖。真正的默认序列化器是StdDateFormat它输出ISO格式。第二层是Spring Boot预设的Builder配置Jackson2ObjectMapperBuilder在spring-boot-autoconfigure模块中定义了一套硬编码的默认行为。例如dateFormat被设为null意味着使用StdDateFormatserializationInclusion默认为JsonInclude.Include.NON_NULLwriteDatesAsTimestamps默认为false即序列化为字符串而非时间戳failOnEmptyBeans默认为true空Bean序列化时报错第三层是用户自定义配置通过Bean声明Jackson2ObjectMapperBuilder或直接Bean ObjectMapper或者通过application.yml中的spring.jackson.*属性。这一层会合并到前两层之上但合并规则有陷阱比如spring.jackson.date-format只影响dateFormat属性但不会自动开启WRITE_DATES_AS_TIMESTAMPSfalse你需要显式配置spring.jackson.write-dates-as-timestampsfalse才能生效。提示很多开发者以为在application.yml里配了date-format就万事大吉结果发现日期还是ISO格式。这是因为date-format只设置了格式对象但ObjectMapper默认仍使用StdDateFormat除非你同时关闭write-dates-as-timestamps并确保dateFormat非空它才会真正使用你指定的SimpleDateFormat。2.2 配置生效的优先级链条哪里改才真正起作用配置不是写在哪都有效它遵循严格的优先级链条。我画过一张调试日志追踪图结论很清晰最底层的ObjectMapper实例永远只认它构造时最终确定的参数值其他地方的配置只是“建议”。优先级从高到低如下Bean ObjectMapper直接定义最高优先级你手动new ObjectMapper()并调用configure()、registerModule()等方法。这种方式完全绕过Spring Boot的Builder机制控制力最强但维护成本高容易遗漏Spring Boot内置的模块如JavaTimeModule。Bean Jackson2ObjectMapperBuilder自定义Builder推荐你返回一个定制的BuilderSpring Boot会用它来构建ObjectMapper。这种方式既能继承Spring Boot的默认模块SimpleModule、CoreJackson2Module等又能精准注入你的配置。例如Bean public Jackson2ObjectMapperBuilder objectMapperBuilder() { return new Jackson2ObjectMapperBuilder() .dateFormat(new SimpleDateFormat(yyyy-MM-dd HH:mm:ss)) .featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS) .featuresToEnable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY); }这里featuresToDisable和featuresToEnable是关键它们直接操作ObjectMapper的SerializationFeature/DeserializationFeature枚举比YAML配置更精确。application.yml中的spring.jackson.*属性便捷但有限适合简单开关如spring.jackson.serialization.write-dates-as-timestampsfalse。但复杂配置如自定义序列化器、模块注册YAML无法表达。JsonSerialize/JsonDeserialize注解字段级覆盖优先级高于全局配置但仅作用于标注的字段或类。例如JsonFormat(patternyyyy-MM-dd)能覆盖全局日期格式但无法解决BigDecimal精度问题。注意JsonInclude注解的优先级高于spring.jackson.default-property-inclusion但低于Bean ObjectMapper的setSerializationInclusion()。这意味着如果你在全局配置了NON_NULL但在某个DTO字段上加了JsonInclude(JsonInclude.Include.ALWAYS)该字段即使为null也会输出——这是设计使然不是bug。2.3 为什么“配了没用”三个最常踩的坑第一个坑混淆SerializationFeature和DeserializationFeature。比如你想让反序列化时把1字符串转成Integer类型需要开启DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY吗不那是处理数组的。正确配置是DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS针对浮点数或DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL针对空字符串。我见过最多的是WRITE_ENUMS_USING_TO_STRING——它控制序列化时枚举用name()还是toString()但反序列化时仍需READ_ENUMS_USING_TO_STRING配合否则PENDING字符串无法反序列化成OrderStatus.PENDING枚举实例。第二个坑JsonAlias在泛型集合里的失效。假设你有个ListUserUser类有JsonAlias({userName, user_name})但反序列化时依然报Unrecognized field userName。原因在于Jackson的泛型擦除机制ListUser在运行时变成ListJackson无法获取User的注解信息。解决方案是用TypeReferenceObjectMapper mapper new ObjectMapper(); ListUser users mapper.readValue(json, new TypeReferenceListUser() {});第三个坑JsonIgnoreProperties的ignoreUnknowntrue与FAIL_ON_UNKNOWN_PROPERTIES冲突。前者是类级别注解后者是全局配置。如果全局开了spring.jackson.deserialization.fail-on-unknown-propertiestrue那么即使你在DTO上写了JsonIgnoreProperties(ignoreUnknown true)反序列化未知字段时依然会抛UnrecognizedPropertyException。因为ignoreUnknown只影响该类的已知属性而FAIL_ON_UNKNOWN_PROPERTIES是解析器级别的开关优先级更高。正确做法是全局关闭它再用JsonIgnoreProperties精细控制。3. 核心配置详解从日期、枚举到空值、精度的实战方案3.1 日期时间告别ISO格式拥抱业务约定业务系统里LocalDateTime、ZonedDateTime、Instant的序列化是最头疼的。默认输出2024-07-15T08:30:45.123但你的数据库字段是datetime类型前端要求2024-07-15 08:30:45。解决方案分三步第一步注册JavaTimeModule并配置格式Spring Boot 2.0默认已注册JavaTimeModule但它的SimpleModule默认不启用WRITE_DATES_AS_TIMESTAMPS。你需要显式配置Bean public Jackson2ObjectMapperBuilder objectMapperBuilder() { return new Jackson2ObjectMapperBuilder() .modules(new JavaTimeModule() .addSerializer(LocalDateTime.class, new LocalDateTimeSerializer( DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))) .addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer( DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))) ) .featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); }这里LocalDateTimeSerializer和LocalDateTimeDeserializer是关键。DateTimeFormatter的模式字符串必须与你数据库和前端约定完全一致。注意yyyy-MM-dd HH:mm:ss中的HH是24小时制hh是12小时制别写错。第二步统一时区处理ZonedDateTime包含时区信息但很多业务不需要。比如你数据库存的是东八区时间但ZonedDateTime.now()返回2024-07-15T08:30:45.12308:00。解决方案是序列化时固定时区.addSerializer(ZonedDateTime.class, new JsonSerializerZonedDateTime() { Override public void serialize(ZonedDateTime value, JsonGenerator gen, SerializerProvider serializers) throws IOException { // 转为东八区时间再序列化 String formatted value.withZoneSameInstant(ZoneId.of(Asia/Shanghai)) .format(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)); gen.writeString(formatted); } });第三步Instant的特殊处理Instant表示UTC时间戳但业务常需转换为本地时间显示。比如Instant.now()存库前端要显示“刚刚”、“2小时前”。这时不应在Jackson层转换而应在DTO里加计算字段public class OrderDTO { private Instant createTime; // 计算字段不参与序列化 JsonIgnore public String getCreateTimeDisplay() { return DateUtil.timeAgo(createTime); // 自定义工具类 } }实操心得别试图在Jackson里做复杂的时区转换逻辑。我试过用JsonSerialize注解加一个万能时区转换器结果在高并发下DateTimeFormatter线程不安全导致日期错乱。后来改成ThreadLocalDateTimeFormatter但维护成本太高。最终方案是数据库存InstantAPI返回String格式的本地时间转换逻辑放在Service层既安全又可控。3.2 枚举类型让PENDING不再变成1枚举序列化有三种模式ORDINAL序号、NAME枚举名、TO_STRINGtoString()返回值。默认是ORDINAL这就是为什么OrderStatus.PENDING变成1。修复方案方案一全局配置WRITE_ENUMS_USING_TO_STRINGBean public Jackson2ObjectMapperBuilder objectMapperBuilder() { return new Jackson2ObjectMapperBuilder() .featuresToEnable(SerializationFeature.WRITE_ENUMS_USING_TO_STRING) .featuresToEnable(DeserializationFeature.READ_ENUMS_USING_TO_STRING); }但这要求所有枚举都重写toString()且toString()必须返回唯一标识符。比如public enum OrderStatus { PENDING(待处理), PROCESSING(处理中), COMPLETED(已完成); private final String desc; OrderStatus(String desc) { this.desc desc; } Override public String toString() { return name(); } // 关键返回name()而非desc }注意toString()必须返回name()否则反序列化失败。因为READ_ENUMS_USING_TO_STRING是按toString()值去匹配枚举实例的。方案二JsonValueJsonCreator推荐在枚举里标注public enum OrderStatus { PENDING, PROCESSING, COMPLETED; JsonValue public String getName() { return this.name().toLowerCase(); } JsonCreator public static OrderStatus fromName(String name) { return OrderStatus.valueOf(name.toUpperCase()); } }这样序列化输出pending反序列化时pending能正确转成PENDING。优势是无需全局配置且JsonValue方法可以返回任意业务值比如pending、processing比name()更友好。方案三JsonEnumFormatJackson 2.12JsonEnumFormat(shape JsonEnumFormat.Shape.AS_STRING) public enum OrderStatus { ... }但需确认Spring Boot版本对应的Jackson版本是否支持。常见问题为什么JsonCreator方法加了static还是报错因为Jackson要求JsonCreator方法必须是public且static参数类型必须是String或int对应name()或ordinal()。如果参数是Object或其他类型会找不到匹配构造器。3.3 空值与Null处理null该不该出现null字段是否输出取决于业务协议。RESTful API通常要求price:null表示价格未定而有些前端框架要求price:0。Jackson提供多层控制JsonInclude注解类/字段级// 类级别所有字段null都不输出 JsonInclude(JsonInclude.Include.NON_NULL) public class ProductDTO { ... } // 字段级别仅price字段null不输出 public class ProductDTO { JsonInclude(JsonInclude.Include.NON_NULL) private BigDecimal price; }全局配置application.ymlspring: jackson: default-property-inclusion: non_null # 所有字段默认non_null serialization: write-nulls: false # 序列化时写null注意default-property-inclusion和write-nulls是互斥的。write-nulls: true会覆盖non_null强制输出所有null。ObjectMapper级配置最灵活Bean public Jackson2ObjectMapperBuilder objectMapperBuilder() { return new Jackson2ObjectMapperBuilder() // 全局设为NON_NULL .serializationInclusion(JsonInclude.Include.NON_NULL) // 但某些字段强制输出null .serializerByType(BigDecimal.class, new NullAwareBigDecimalSerializer()); }自定义序列化器示例public class NullAwareBigDecimalSerializer extends JsonSerializerBigDecimal { Override public void serialize(BigDecimal value, JsonGenerator gen, SerializerProvider serializers) throws IOException { if (value null) { gen.writeNull(); // 强制写null } else { gen.writeNumber(value); } } }实操心得我们曾遇到支付接口要求discount:null表示无折扣但BigDecimal字段默认为0。解决方案是在DTO里用JsonInclude(JsonInclude.Include.CUSTOM)配合自定义判断器JsonInclude(value JsonInclude.Include.CUSTOM, valueFilter DiscountNullFilter.class) private BigDecimal discount; public static class DiscountNullFilter { public boolean equals(BigDecimal value) { return value null || value.compareTo(BigDecimal.ZERO) 0; } }这样discountnull或discount0都输出discount:null完美匹配协议。3.4 数字精度BigDecimal的坑与Double的陷阱BigDecimal序列化默认保留全部精度1.00变成1.00000000000000000000。Double则可能因二进制浮点误差变成1.0000000000000002。解决方案BigDecimal精度控制Bean public Jackson2ObjectMapperBuilder objectMapperBuilder() { return new Jackson2ObjectMapperBuilder() .serializerByType(BigDecimal.class, new BigDecimalSerializer()); } public class BigDecimalSerializer extends JsonSerializerBigDecimal { Override public void serialize(BigDecimal value, JsonGenerator gen, SerializerProvider serializers) throws IOException { if (value null) { gen.writeNull(); } else { // 保留2位小数四舍五入 gen.writeNumber(value.setScale(2, RoundingMode.HALF_UP)); } } }Double精度修复.serializerByType(Double.class, new JsonSerializerDouble() { Override public void serialize(Double value, JsonGenerator gen, SerializerProvider serializers) throws IOException { if (value null) { gen.writeNull(); } else { // 转为BigDecimal再格式化避免浮点误差 BigDecimal bd BigDecimal.valueOf(value); gen.writeNumber(bd.setScale(2, RoundingMode.HALF_UP)); } } });注意不要用String.format(%.2f, value)因为Double本身就有精度损失。比如0.1 0.2在Java里是0.30000000000000004String.format会输出0.30但BigDecimal.valueOf(0.10.2)是0.3这才是真实值。所以必须先转BigDecimal再setScale。4. 高级技巧自定义序列化器、反序列化漏洞防护与性能调优4.1 自定义序列化器处理复杂业务对象当标准序列化器无法满足需求时比如User对象要根据当前登录用户角色返回不同字段public class User { private Long id; private String name; private String email; private String phone; // 敏感字段 }管理员能看到phone普通用户看不到。标准JsonView只能静态分组无法动态判断。解决方案是自定义序列化器public class UserSerializer extends JsonSerializerUser { Override public void serialize(User user, JsonGenerator gen, SerializerProvider serializers) throws IOException { gen.writeStartObject(); gen.writeNumberField(id, user.getId()); gen.writeStringField(name, user.getName()); gen.writeStringField(email, user.getEmail()); // 动态判断是否输出phone Authentication auth SecurityContextHolder.getContext().getAuthentication(); if (auth ! null auth.getAuthorities().contains(new SimpleGrantedAuthority(ROLE_ADMIN))) { gen.writeStringField(phone, user.getPhone()); } gen.writeEndObject(); } }然后在User类上标注JsonSerialize(using UserSerializer.class) public class User { ... }实操心得自定义序列化器里不要调用objectMapper.writeValueAsString()这会导致递归调用。所有字段必须用JsonGenerator的writeXXXField()方法手动写出。另外SecurityContextHolder在异步线程里可能为空所以要在Controller层提前获取权限信息作为参数传入序列化器。4.2 反序列化安全防范pikachu类漏洞pikachu反序列化漏洞本质是Jackson允许反序列化任意类攻击者构造恶意JSON触发com.sun.rowset.JdbcRowSetImpl等危险类的setAutoCommit方法执行命令。Spring Boot默认已禁用大部分危险类但需双重加固第一步禁用DefaultTypingDefaultTyping是最大风险源它允许JSON里指定类名{class:java.lang.ProcessBuilder,command:[calc]}Spring Boot默认不启用DefaultTyping但如果你手动配置过objectMapper.enableDefaultTyping()必须移除。检查所有Bean ObjectMapper定义确保没有enableDefaultTyping()调用。第二步白名单策略Jackson 2.10Bean public Jackson2ObjectMapperBuilder objectMapperBuilder() { return new Jackson2ObjectMapperBuilder() .deserializerByClass(JsonNode.class, new SafeJsonNodeDeserializer()) .modules(new SimpleModule() .setDeserializerModifier(new BeanDeserializerModifier() { Override public BeanDeserializerBuilder updateBuilder(DeserializationConfig config, BeanDescription beanDesc, BeanDeserializerBuilder builder) { // 只允许反序列化白名单内的类 if (!ALLOWED_CLASSES.contains(beanDesc.getBeanClass().getName())) { throw new IllegalArgumentException(Forbidden class: beanDesc.getBeanClass().getName()); } return builder; } })); }白名单ALLOWED_CLASSES应只包含你的DTO类如com.example.dto.*。第三步禁用ObjectMapper的enableDefaultTyping和activateDefaultTyping在application.yml中强制关闭spring: jackson: deserialization: fail-on-unknown-properties: true # 确保以下配置不存在或显式设为false提示fastjson的反序列化漏洞更严重因为它默认开启autoType。而Jackson默认是安全的但一旦你为了兼容旧系统启用了DefaultTyping风险就来了。所以原则是永远不要启用DefaultTyping除非你100%信任所有输入源。4.3 性能调优减少GC压力与提升吞吐量Jackson默认配置对小数据友好但高并发下ObjectMapper的writeValueAsString()会创建大量临时对象增加GC压力。优化方案复用ObjectWriter和ObjectReaderObjectMapper是线程安全的但writeValueAsString()每次都会创建ObjectWriter。预先构建并缓存Component public class JsonHelper { private final ObjectWriter userWriter; private final ObjectReader userReader; public JsonHelper(ObjectMapper objectMapper) { this.userWriter objectMapper.writerFor(User.class); this.userReader objectMapper.readerFor(User.class); } public String writeUser(User user) throws JsonProcessingException { return userWriter.writeValueAsString(user); } public User readUser(String json) throws IOException { return userReader.readValue(json); } }禁用不必要的特性Bean public Jackson2ObjectMapperBuilder objectMapperBuilder() { return new Jackson2ObjectMapperBuilder() // 禁用反射提升性能 .featuresToDisable(MapperFeature.USE_ANNOTATIONS) // 禁用动态类加载 .featuresToDisable(DeserializationFeature.USE_BASE64_FOR_BYTE_ARRAYS) // 禁用XML兼容模式 .featuresToDisable(DeserializationFeature.UNWRAP_ROOT_VALUE); }使用JsonGenerator流式写入对于大数据量导出避免writeValueAsString()生成完整字符串再写入响应流GetMapping(/export) public void export(HttpServletResponse response) throws IOException { response.setContentType(application/json); JsonGenerator generator objectMapper.getFactory().createGenerator(response.getOutputStream()); generator.writeStartArray(); for (User user : userService.findAll()) { objectMapper.writeValue(generator, user); // 直接写入流 } generator.writeEndArray(); generator.flush(); }实测数据在QPS 500的订单查询接口中将ObjectMapper.writeValueAsString()改为预编译ObjectWriterGC Young GC频率从每秒3次降到每分钟1次平均响应时间从85ms降至42ms。关键在于ObjectWriter复用了SerializerProvider和Serializers缓存避免了重复查找序列化器的开销。5. 常见问题速查表从配置不生效到序列化异常的实战排障问题现象根本原因解决方案实操验证步骤日期仍是ISO格式spring.jackson.date-format不生效spring.jackson.write-dates-as-timestamps默认为true覆盖了date-format在application.yml中添加spring.jackson.write-dates-as-timestamps: false启动应用调用接口用curl检查响应JSON中的日期格式枚举反序列化失败报Can not construct instance of com.example.StatusDeserializationFeature.READ_ENUMS_USING_TO_STRING未开启或JsonCreator方法签名错误检查JsonCreator是否为public static参数是否为String全局开启READ_ENUMS_USING_TO_STRING写单元测试mapper.readValue(\PENDING\, Status.class)null字段未输出但协议要求必须存在spring.jackson.serialization.write-nulls未设为true或JsonInclude注解覆盖了全局配置移除类/字段上的JsonInclude在application.yml中设spring.jackson.serialization.write-nulls: true用Postman发送含null字段的JSON检查响应是否包含该字段BigDecimal精度丢失1.00变成1.0BigDecimal序列化器未自定义使用了默认的ToStringSerializer创建BigDecimalSerializer在ObjectMapper中注册单元测试mapper.writeValueAsString(new BigDecimal(1.00))检查输出是否为1.00反序列化时1无法转成Integer报Can not construct instance of java.lang.IntegerDeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY未开启且JSON是字符串而非数字开启ACCEPT_SINGLE_VALUE_AS_ARRAY或确保前端发送数字1而非字符串1测试JSON{age:1}检查是否能反序列化为Integer自定义序列化器未生效仍走默认逻辑JsonSerialize(using XXX.class)未加在字段或类上或ObjectMapper未注册该序列化器检查注解位置若用Bean ObjectMapper需调用registerModule()在序列化器serialize()方法里加断点看是否被调用高并发下DateTimeFormatter报java.lang.IllegalStateException: Multiple calls to setFormatterDateTimeFormatter非线程安全多个线程同时调用withZone()使用DateTimeFormatter的withZone()返回新实例或用ThreadLocalDateTimeFormatter将DateTimeFormatter.ofPattern(...).withZone(...)改为DateTimeFormatter.ofPattern(...).withZone(...).format(time)排查技巧当配置“不生效”时第一件事是打印ObjectMapper的配置状态Autowired private ObjectMapper objectMapper; PostConstruct public void printConfig() { System.out.println(Serialization features: objectMapper.getSerializationConfig().getDefaultVisibilityChecker()); System.out.println(Serialization inclusion: objectMapper.getSerializationConfig().getDefaultPropertyInclusion()); System.out.println(Deserialization features: objectMapper.getDeserializationConfig().getDefaultVisibilityChecker()); }这能直接看到Spring Boot最终应用了哪些配置比猜配置文件更可靠。最后分享一个小技巧在开发环境启用spring.jackson.serialization.indent-outputtrue让JSON自动缩进。虽然线上不用但调试时能一眼看出字段嵌套关系比压缩JSON快十倍定位问题。这个配置不影响性能只在ObjectWriter创建时生效上线前关掉即可。
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
