告别千篇一律：Gson FormattingStyle让JSON输出随心所欲
项目地址: https://gitcode.com/gh_mirrors/gs/gson 你还在为JSON输出格式烦恼吗？默认的紧凑格式阅读困难，漂亮打印又不够灵活？本文将带你掌握Gson的FormattingStyle工具，通过简单配置实现从紧凑到美观的全自定义JSON格式，让数据展示更符合业务需求。读完本文你将学会：基础格式切换、自定义缩进与换行、分隔符空格控制，以及三种实用场景的完整实现方案。
认识FormattingStyle：JSON格式的总开关
Gson 2.11.0版本引入的FormattingStyle类（gson/src/main/java/com/google/gson/FormattingStyle.java）是控制JSON输出格式的核心组件。它提供了三种基础配置维度：
- 换行符（Newline）：控制JSON层级之间的换行方式
- 缩进字符串（Indent）：定义嵌套结构的缩进样式
- 分隔符空格（Space After Separators）：控制逗号和冒号后是否添加空格
Gson默认提供两种预定义样式，可通过GsonBuilder快速启用：
// 紧凑格式（默认）：无换行、无缩进、无空格分隔
Gson compactGson = new GsonBuilder()
.setFormattingStyle(FormattingStyle.COMPACT)
.create();
// 漂亮打印格式：换行+2空格缩进+冒号后空格
Gson prettyGson = new GsonBuilder()
.setFormattingStyle(FormattingStyle.PRETTY)
.create();
// 等价于传统的setPrettyPrinting()方法
基础格式切换：三行代码实现样式转换
从紧凑到美观的一键切换
假设我们有一个用户数据类：
class User {
String name = "Alice";
int age = 30;
String[] tags = {"user", "premium"};
}
使用默认紧凑格式序列化的结果是单行字符串，可读性较差：
{"name":"Alice","age":30,"tags":["user","premium"]}
通过FormattingStyle.PRETTY切换为美观格式：
Gson gson = new GsonBuilder()
.setFormattingStyle(FormattingStyle.PRETTY)
.create();
System.out.println(gson.toJson(new User()));
输出立即变得层次分明：
{
"name": "Alice",
"age": 30,
"tags": [
"user",
"premium"
]
}
源码中的格式定义
查看FormattingStyle类源码可知，PRETTY格式的默认配置为：
// 源码片段：FormattingStyle.java 第64行
public static final FormattingStyle PRETTY = new FormattingStyle("\n", " ", true);
这解释了为何默认漂亮打印会使用\n换行、两个空格缩进，并在冒号后添加空格。
进阶自定义：打造专属格式
自定义缩进与换行
FormattingStyle提供了流畅的链式API，让我们可以精确控制每一个格式细节。例如创建一个使用4个空格缩进和Windows风格CRLF换行的格式：
FormattingStyle customStyle = FormattingStyle.PRETTY
.withIndent(" ") // 4个空格缩进
.withNewline("\r\n"); // Windows换行符
Gson gson = new GsonBuilder().setFormattingStyle(customStyle).create();
对于需要适配不同系统换行符的场景，可以动态获取系统默认值：
String systemLineSeparator = System.lineSeparator();
FormattingStyle systemStyle = FormattingStyle.PRETTY.withNewline(systemLineSeparator);
控制分隔符空格
通过withSpaceAfterSeparators方法可以精确控制逗号和冒号后的空格：
// 紧凑格式但保留冒号后空格
FormattingStyle compactWithSpaces = FormattingStyle.COMPACT
.withSpaceAfterSeparators(true);
// 输出: {"name": "Alice", "age": 30}
// 漂亮格式但移除所有空格
FormattingStyle prettyNoSpaces = FormattingStyle.PRETTY
.withSpaceAfterSeparators(false);
// 输出:
// {
// "name":"Alice",
// "age":30
// }
Gson的JsonWriterTest（gson/src/test/java/com/google/gson/stream/JsonWriterTest.java）验证了这些格式控制的正确性，特别是第942-967行的测试用例详细检查了缩进和换行的各种组合。
实用场景：三种典型业务需求实现
场景一：日志系统的可读性优化
日志中的JSON通常需要兼顾可读性和存储效率。解决方案是：开发环境使用详细格式，生产环境切换为紧凑格式。
FormattingStyle logStyle = isProduction() ?
FormattingStyle.COMPACT :
FormattingStyle.PRETTY.withIndent(" ");
Gson logGson = new GsonBuilder()
.setFormattingStyle(logStyle)
.serializeNulls() // 保留null值便于调试
.create();
logger.info("用户操作: {}", logGson.toJson(userAction));
场景二：API响应的定制化展示
为不同客户端提供差异化的JSON格式：给Web前端的响应使用标准漂亮格式，给移动端的响应使用紧凑格式减少流量。
// 根据请求头选择格式
String format = request.getHeader("X-Json-Format");
FormattingStyle style = "pretty".equals(format) ?
FormattingStyle.PRETTY :
FormattingStyle.COMPACT;
response.getWriter().write(new GsonBuilder()
.setFormattingStyle(style)
.create()
.toJson(apiResponse));
场景三：配置文件生成器
生成人类可编辑的JSON配置文件时，需要特定的缩进和注释友好格式。通过组合FormattingStyle和自定义TypeAdapter实现：
FormattingStyle configStyle = FormattingStyle.PRETTY
.withIndent(" ") // 2空格缩进
.withNewline("\n"); // Unix换行
Gson configGson = new GsonBuilder()
.setFormattingStyle(configStyle)
.registerTypeAdapter(Config.class, new ConfigTypeAdapter())
.create();
// 生成带注释的配置文件（通过TypeAdapter实现）
Files.write(Paths.get("app.config.json"),
configGson.toJson(configObject).getBytes());
避坑指南：常见问题与解决方案
缩进字符限制
FormattingStyle严格限制缩进只能使用空格和制表符。尝试使用其他字符会抛出IllegalArgumentException：
// 会抛出异常：Only combinations of spaces and tabs are allowed in indent.
FormattingStyle invalidIndent = FormattingStyle.PRETTY.withIndent("|-");
同样，换行符只能包含\r和\n字符，如测试用例FormattingStyleTest（gson/src/test/java/com/google/gson/functional/FormattingStyleTest.java）第188-200行所示，任何其他字符都会触发参数校验失败。
格式切换的性能影响
虽然漂亮打印会增加CPU开销，但Gson的性能测试（gson/src/test/java/com/google/gson/metrics/PerformanceTest.java）显示，对于10KB以下的JSON，格式转换的性能差异可以忽略不计。建议仅对大型JSON（>100KB）进行格式优化评估。
与@SerializedName的配合
自定义字段名不会影响格式设置，但需要注意在使用紧凑格式时，过长的字段名可能降低可读性。建议结合FieldNamingPolicy使用：
GsonBuilder()
.setFieldNamingPolicy(FieldNamingPolicy.LOWER_CAMEL_CASE)
.setFormattingStyle(FormattingStyle.PRETTY)
.create();
总结：格式即体验
FormattingStyle作为Gson的格式控制中心，通过简单直观的API提供了从紧凑到美观的全谱系格式控制。无论是日常开发调试、日志分析还是用户界面展示，合适的JSON格式都能显著提升工作效率和用户体验。
官方文档（UserGuide.md）建议，对于大多数应用，使用默认的COMPACT和PRETTY两种预设即可满足需求。当需要特殊格式时，通过withIndent()、withNewline()和withSpaceAfterSeparators()的组合，可以精确调整每一个格式细节，让JSON输出真正为业务服务。
掌握FormattingStyle，让你的JSON不再千篇一律！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
