Jackson ObjectMapper JSON美化输出高级定制教程

本教程详细介绍了如何使用Jackson `ObjectMapper`实现JSON的精确美化输出。当默认的 `SerializationFeature.INDENT_OUTPUT` 无法满足特定格式要求时，可以通过定制 `DefaultPrettyPrinter` 来精细控制对象和数组的缩进、换行。文章将指导读者创建并应用自定义的 `PrettyPrinter`，从而生成符合严格格式规范的JSON输出，并提供示例代码演示其效果。

在Java开发中，Jackson ObjectMapper 是一个广泛使用的库，用于JSON数据的序列化和反序列化。为了提高JSON的可读性，我们经常需要对其进行“美化输出”（Pretty Printing），即添加缩进和换行。Jackson提供了 SerializationFeature.INDENT_OUTPUT 特性来实现基本的JSON美化。然而，在某些场景下，默认的美化输出可能无法满足特定的格式要求，例如对数组和对象的起始/结束括号的换行、空数组内部的空格，或者键值对之间冒号的空格等。

默认美化输出的局限性

当我们使用 objectMapper.configure(SerializationFeature.INDENT_OUTPUT, true) 时，Jackson会采用其内置的默认美化策略。虽然这通常能生成易于阅读的JSON，但在面对诸如以下细致的格式要求时，可能会力不从心：

• 在JSON数组 [ 之后立即换行。
• 在JSON对象 } 之后立即换行。
• 空数组 [] 内部不包含空格（而不是 [ ]）。
• 键值对之间冒号 : 两侧不包含空格（例如 "key":"value" 而不是 "key" : "value"）。

如果默认的 INDENT_OUTPUT 无法达到预期效果，我们需要深入定制Jackson的 PrettyPrinter 机制。

使用 DefaultPrettyPrinter 进行高级定制

Jackson库提供了一个 DefaultPrettyPrinter 类，允许开发者对JSON的输出格式进行更细粒度的控制。通过配置 DefaultPrettyPrinter，我们可以精确定义对象和数组的缩进行为。

DefaultPrettyPrinter 内部使用 Indenter 接口来处理实际的缩进逻辑。Jackson提供了一个默认的实现 DefaultIndenter，它可以用于配置对象和数组的缩进方式。

1. 定制 DefaultPrettyPrinter 实例

首先，我们需要创建一个 DefaultPrettyPrinter 的实例，并使用 DefaultIndenter 来指定对象和数组的缩进方式。

import com.fasterxml.jackson.core.util.DefaultIndenter;
import com.fasterxml.jackson.core.util.DefaultPrettyPrinter;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;

// ... 其他必要的导入

public class CustomJsonPrettyPrinter {

    public static void main(String[] args) throws Exception {
        // 1. 创建并配置 DefaultPrettyPrinter
        DefaultPrettyPrinter printer = new DefaultPrettyPrinter();

        // 配置对象内部的缩进器，确保在 '{' 后和 '}' 前换行并缩进
        printer.indentObjectsWith(new DefaultIndenter("  ", DefaultIndenter.SYS_LF)); // 使用两个空格缩进，系统默认换行符

        // 配置数组内部的缩进器，确保在 '[' 后和 ']' 前换行并缩进
        printer.indentArraysWith(new DefaultIndenter("  ", DefaultIndenter.SYS_LF)); // 使用两个空格缩进，系统默认换行符

        // ... 后续步骤
    }
}

在 DefaultIndenter 的构造函数中，第一个参数是缩进字符串（例如 " " 表示两个空格），第二个参数是换行符（DefaultIndenter.SYS_LF 表示使用系统默认的换行符）。

2. 将定制的 PrettyPrinter 应用到 ObjectMapper

配置好 DefaultPrettyPrinter 后，需要将其设置给 ObjectMapper，以便在序列化时使用。

        // ... (接上一步代码)

        // 2. 将定制的 PrettyPrinter 设置给 ObjectMapper
        ObjectMapper mapper = new ObjectMapper();
        mapper.enable(SerializationFeature.INDENT_OUTPUT); // 仍然需要启用INDENT_OUTPUT特性
        mapper.setDefaultPrettyPrinter(printer);

        // ... 后续步骤

注意： 即使使用了自定义的 PrettyPrinter，仍然建议启用 SerializationFeature.INDENT_OUTPUT 特性，以确保 ObjectMapper 知道需要进行美化输出。setDefaultPrettyPrinter 方法会覆盖默认的 PrettyPrinter 实现。

3. 执行序列化

最后，使用配置好的 ObjectMapper 进行JSON序列化。为了确保使用自定义的 PrettyPrinter，最稳妥的方式是显式地通过 writerWithDefaultPrettyPrinter() 方法获取一个 ObjectWriter 实例进行写入。

        // ... (接上一步代码)

        // 示例数据模型
        public static class ActionOutput {
            private String key1;
            private java.util.List key2;
            private String key3;

            public ActionOutput(String key1, java.util.List key2, String key3) {
                this.key1 = key1;
                this.key2 = key2;
                this.key3 = key3;
            }

            // Getters
            public String getKey1() { return key1; }
            public java.util.List getKey2() { return key2; }
            public String getKey3() { return key3; }
        }

        // 3. 准备数据并执行序列化
        java.util.List actions = java.util.List.of(
            new ActionOutput("value", java.util.List.of(), null),
            new ActionOutput("value", java.util.List.of(), null)
        );

        // 序列化到字符串
        String jsonRes = mapper
            .writerWithDefaultPrettyPrinter() // 确保使用默认（此处为定制的）PrettyPrinter
            .writeValueAsString(actions);

        System.out.println(jsonRes);

        // 序列化到文件 (假设args[1]是文件路径)
        // mapper.writerWithDefaultPrettyPrinter().writeValue(new java.io.File(args[1]), actions);
    }
}

完整示例与输出

结合上述步骤，以下是一个完整的示例，展示了如何通过定制 DefaultPrettyPrinter 来实现特定的JSON美化输出：

import com.fasterxml.jackson.core.util.DefaultIndenter;
import com.fasterxml.jackson.core.util.DefaultPrettyPrinter;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;

import java.util.List;

import java.io.File;

public class CustomJsonPrettyPrinterDemo {

    // 示例数据模型
    public static class ActionOutput {
        private String key1;
        private List key2;
        private String key3;

        // all-args constructor
        public ActionOutput(String key1, List key2, String key3) {
            this.key1 = key1;
            this.key2 = key2;
            this.key3 = key3;
        }

        // Getters (Jackson requires getters for serialization)
        public String getKey1() { return key1; }
        public List getKey2() { return key2; }
        public String getKey3() { return key3; }

        // Setters can be omitted if not needed for deserialization
    }

    public static void main(String[] args) throws Exception {
        // 1. 创建并配置 DefaultPrettyPrinter
        DefaultPrettyPrinter printer = new DefaultPrettyPrinter();

        // 配置对象和数组的缩进器
        // DefaultIndenter("  ", DefaultIndenter.SYS_LF) 表示使用两个空格缩进，并使用系统默认的换行符
        printer.indentObjectsWith(new DefaultIndenter("  ", DefaultIndenter.SYS_LF));
        printer.indentArraysWith(new DefaultIndenter("  ", DefaultIndenter.SYS_LF));

        // 2. 将定制的 PrettyPrinter 设置给 ObjectMapper
        ObjectMapper mapper = new ObjectMapper();
        mapper.enable(SerializationFeature.INDENT_OUTPUT); // 启用美化输出特性
        mapper.setDefaultPrettyPrinter(printer); // 设置自定义的PrettyPrinter

        // 3. 准备数据
        List actions = List.of(
            new ActionOutput("value", List.of(), null),
            new ActionOutput("value", List.of(), null)
        );

        // 4. 执行序列化并打印结果
        String jsonRes = mapper
            .writerWithDefaultPrettyPrinter() // 获取一个使用默认（定制）PrettyPrinter的writer
            .writeValueAsString(actions);

        System.out.println(jsonRes);

        // 如果需要写入文件
        // String filePath = "output.json"; // 假设文件路径
        // mapper.writerWithDefaultPrettyPrinter().writeValue(new File(filePath), actions);
        // System.out.println("JSON successfully written to " + filePath);
    }
}

上述代码的输出将是：

[
  {
    "key1" : "value",
    "key2" : [ ],
    "key3" : null
  },
  {
    "key1" : "value",
    "key2" : [ ],
    "key3" : null
  }
]

可以看到，通过定制 DefaultPrettyPrinter，我们成功地控制了JSON数组和对象的换行与缩进。数组 [ 后和对象 } 后的换行都得到了满足。

注意事项与高级定制

• 键值对和空数组的空格： 请注意，即使使用 DefaultPrettyPrinter 和 DefaultIndenter，默认情况下，键值对之间冒号 ` 两侧仍然会有一个空格（"key" : "value"），空数组内部也可能包含空格（[ ]）。如果需要更严格的格式，例如"key":"value"或[]，可能需要进一步定制DefaultPrettyPrinter` 的行为。
  • 对于键值对的空格，DefaultPrettyPrinter 提供了 withSpacesInObjectEntries(boolean) 方法。将其设置为 false 可以移除冒号两侧的空格。
  • 对于空数组的空格，DefaultPrettyPrinter 默认会在 startArray() 和 endArray() 之间插入一个空格如果数组是空的。要完全移除，可能需要更复杂的自定义 PrettyPrinter 实现，或者在序列化前对数据进行预处理。
• 性能考量： JSON美化输出会增加序列化过程的计算开销和输出文件的大小。对于性能敏感的场景或传输大量数据时，应权衡美观性和性能，按需启用或定制美化输出。
• 线程安全： ObjectMapper 在配置完成后是线程安全的，可以重复使用。DefaultPrettyPrinter 实例在配置完成后也可以被多个 ObjectMapper 或 ObjectWriter 共享，但如果需要在运行时动态修改其配置，则需要为每个 ObjectWriter 创建独立的 PrettyPrinter 实例。

通过本教程，您应该能够熟练掌握Jackson ObjectMapper 的JSON美化输出高级定制，以满足各种复杂的格式要求。