Jackson 3.x 中 JsonGenerator 与 PrettyPrinter 的配置注意事项

问题背景

在 Jackson 3.0.0-rc3 版本中，开发者发现当通过 ObjectWriter 配置 PrettyPrinter 后，使用 writeValue(JsonGenerator, Object) 方法时，格式化配置未生效。而同样的配置在使用 writeValue(OutputStream, Object) 时却能正常工作。这一行为与 Jackson 2.x 版本的表现不一致。

技术原理分析

不可变设计的影响

Jackson 3.x 采用了更严格的不可变（immutable）设计原则。这意味着：

1. JsonGenerator 一旦被创建，其所有配置（包括格式化设置）就被固定
2. ObjectWriter 无法修改已存在的 JsonGenerator 实例的任何属性

配置生效时机

PrettyPrinter 的配置必须在 JsonGenerator 创建时确定。因此：

• 有效方式：通过 ObjectWriter.createGenerator() 创建 JsonGenerator，此时会继承 writer 的所有配置
• 无效方式：预先创建 JsonGenerator 再传递给 writer，此时无法应用后续的格式化配置

解决方案

开发者需要调整代码结构，改为通过 ObjectWriter 创建生成器：

// 正确用法
JsonGenerator generator = mapper.writer()
    .with(prettyPrinter)
    .createGenerator(outputStream);
writer.writeValue(generator, bean);

而不是：

// 错误用法（配置不会生效）
JsonGenerator generator = mapper.createGenerator(outputStream);
mapper.writer().with(prettyPrinter).writeValue(generator, bean);

设计考量

这种改变虽然带来了使用习惯上的调整，但带来了以下优势：

1. 线程安全性：不可变对象天然线程安全
2. 明确性：配置生效时机更加明确和可预测
3. 一致性：所有配置都通过同一入口（ObjectWriter）管理

迁移建议

对于从 Jackson 2.x 迁移的用户：

1. 检查所有直接使用 JsonFactory 创建解析器/生成器的代码
2. 改为通过 ObjectReader/ObjectWriter 的工厂方法创建
3. 确保所有配置都在创建前通过 withXXX() 方法设置

总结

Jackson 3.x 通过不可变设计提高了稳定性和可预测性，但要求开发者更严格地遵循配置流程。理解这一设计原则后，可以避免类似 PrettyPrinter 配置失效的问题，并编写出更健壮的 JSON 处理代码。