Jackson-databind 中 JsonSerializer 的正确使用方式：writeRaw 与 writeRawValue 的区别

在 Java 的 JSON 处理领域，Jackson 是最受欢迎的库之一。其中 jackson-databind 模块提供了强大的对象序列化和反序列化功能。本文将深入探讨一个常见的序列化陷阱：JsonSerializer 中 writeRaw 和 writeRawValue 方法的区别。

问题现象

开发者在自定义序列化器时，可能会遇到 JSON 输出格式不正确的问题。具体表现为字段名和字段值之间缺少必要的冒号分隔符，导致生成的 JSON 格式错误。例如：

{
  "inner" {
    "a" : "b"
  }
}

正确的 JSON 应该在 "inner" 和后面的对象之间有一个冒号：

{
  "inner" : {
    "a" : "b"
  }
}

问题根源

这个问题的根本原因在于错误地使用了 JsonGenerator 的 writeRaw 方法。writeRaw 方法如其名，会直接将字符串原样写入输出，不做任何格式化处理，包括不会添加必要的分隔符。

解决方案

正确的做法是使用 writeRawValue 方法。这个方法不仅会写入内容，还会确保 JSON 结构的完整性，自动添加必要的分隔符和格式。

public class InnerSerializer extends JsonSerializer<Inner> {
    @Override
    public void serialize(Inner value, JsonGenerator gen, SerializerProvider serializers) throws IOException {
        gen.writeRawValue("{\"a\": \"b\"}");  // 使用 writeRawValue 而非 writeRaw
    }
}

方法对比

方法	行为	适用场景
writeRaw	直接写入原始字符串，不做任何处理	需要完全控制输出内容，如写入注释等非标准JSON内容
writeRawValue	写入内容并确保JSON结构完整	标准JSON序列化场景

最佳实践

1. 优先使用 writeRawValue：在大多数标准JSON序列化场景下，应该使用 writeRawValue 方法。

2. 谨慎使用 writeRaw：只有在需要完全控制输出内容，或者需要写入非标准JSON内容（如注释）时才使用 writeRaw。

3. 考虑使用标准序列化方法：对于简单场景，考虑使用 gen.writeStartObject() 和 gen.writeFieldName() 等标准方法，而不是直接写入原始字符串。

总结

理解 Jackson 中不同写入方法的区别对于生成正确的 JSON 格式至关重要。writeRawValue 方法会自动处理 JSON 结构所需的格式元素，而 writeRaw 则提供更底层、更直接的控制。在大多数情况下，writeRawValue 是更安全、更合适的选择。

通过正确使用这些方法，开发者可以避免 JSON 格式错误，确保应用程序与其他系统的顺畅交互。