Gson Builder — 基础& 命名策略

Gson Builder — 基础& 命名策略

这篇文章，我们将开始本系列的一个新的文集，这一部分将使用GsonBuilder定制Gson部分模块的行为。

GsonBuilder 基础

在之前发布的博客中，我们写了一些只需要用Gson gson = new Gson();实现一个Gson实例的例子。当只需要使用Gson自己的标准设置的时候非常有用。然而，Gson也有许多小设置可以供更改，如果你需要以非标准的方式使用Gson时，这将非常方便。为了改变某些设置，你可以利用GsonBuilder去创建一个带有自定义设置的新的Gson实例。

// previously
Gson gson = new Gson();

// now using GsonBuilder
GsonBuilder gsonBuilder = new GsonBuilder();  
Gson gson = gsonBuilder.create();  
1
2
3
4
5
6

GsonBuilder类提供了一个.create()方法，它返回一个Gson实例。用这个Gson实例，你可以做我们之前展示的所有事情：对JSON进行映射各种各样的数据。

命名策略

准备介绍GsonBuilder的第一个设置项是命名策略。我们总是假设你的Java模型文件和JSON之间有效转换，是基于Api请求和响应采用同样的命名模式。我们已经展示过如何用@SerializedName改变字段的命名去改变单个模式的属性序列化。然而，如果你的API和你的Java模型在命名上并不统一，这可能需要痛苦地用@SerializedName声明改变上百个属性名字。

因此，Gson提供了配置和定义FieldNamingPolicy。为了展示的目的，我们改变我们UserSimple模型，并给这些属性一些新的名字：

public class UserNaming {  
    String Name;
    String email_of_developer;
    boolean isDeveloper;
    int _ageOfDeveloper;
}
1
2
3
4
5
6

如你所见，我们在一个模型里统一了所有命名标准。这将导致生成一些样子有趣的JSON,更容易看到各种命名策略怎样影响它们。你可以在GsonBuilder设置策略:

GsonBuilder gsonBuilder = new GsonBuilder();  
gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.IDENTITY);  
Gson gson = gsonBuilder.create();  
1
2
3

所有使用上述Gson实例的转换，都会用命名策略FieldNamingPolicy.IDENTITY。 在接下来的几节中我们将探讨这意味着什么,以及如何将预定义的字段命名的政策行为。让我们从最简单的开始:IDENTITY。

字段命名策略 - IDENTITY

当序列化一个对象时，字段的命名策略IDENTITY使用了与Java模型同样的命名。无论你在你的Java模型里使用什么样的命名标准，JSON都会使用同样的。我们上述的奇怪的命名模型，产生了下面的JSON：

GsonBuilder gsonBuilder = new GsonBuilder();  
gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.IDENTITY);  
Gson gson = gsonBuilder.create();

UserNaming user = new UserNaming("Norman", "norman@futurestud.io", true, 26);  
String usersJson = gson.toJson(user);  
1
2
3
4
5
6

usersJson会包含：

{
  "Name": "Norman",
  "_ageOfDeveloper": 26,
  "email_of_developer": "norman@futurestud.io",
  "isDeveloper": true
}
1
2
3
4
5
6

如你所见，没有一个字段的命名被改变了。名字是从模型中原封不动地拷贝过来。如果你没有设置命名策略或者没有使用GsonBuilder，而是直接使用new Gson()创建的Gson实例，它也会用这个策略。

字段命名策略 - LOWER_CASE_WITH_UNDERSCORES

第二个要展示的策略是：LOWER_CASE_WITH_UNDERSCORES。命名是相当清楚，但让我们在同样的例子里试试：

GsonBuilder gsonBuilder = new GsonBuilder();  
gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES);  
Gson gson = gsonBuilder.create();

UserNaming user = new UserNaming("Norman", "norman@futurestud.io", true, 26);  
String usersJson = gson.toJson(user); 
1
2
3
4
5
6

这个LOWER_CASE_WITH_UNDERSCORES会先根据大小写字符拆分属性名称，再用小写替换掉大写，替换掉的字母以_开头。我们模型里两个属性被改变了：

{
  "name": "Norman",
  "_age_of_developer": 26,
  "email_of_developer": "norman@futurestud.io",
  "is_developer": true
}
1
2
3
4
5
6

isDeveloper和_ageOfDeveloper被_分割开。注意_ageOfDeveloper原本就有的_不受影响！如果你想要使用破折号，而不是下划线，下一节是为这个准备的。

译者注：这里Name属性的首字母N变成了小写name，并没有被添加_等分隔符，可见，_等分隔符号仅在字段的中间产生。

字段命名策略 - LOWER_CASE_WITH_DASHES

第三个要介绍的策略是LOWER_CASE_WITH_DASHES.它跟之前介绍的LOWER_CASE_WITH_UNDERSCORES使用一样的系统,但用-去分隔字段。让我们运行一下下面的代码吧：

GsonBuilder gsonBuilder = new GsonBuilder();  
gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_DASHES);  
Gson gson = gsonBuilder.create();

UserNaming user = new UserNaming("Norman", "norman@futurestud.io", true, 26);  
String usersJson = gson.toJson(user);  
1
2
3
4
5
6

生成一个新的uersJson，如下：

{
  "name": "Norman",
  "_age-of-developer": 26,
  "email_of_developer": "norman@futurestud.io",
  "is-developer": true
}

1
2
3
4
5
6
7

请注意，仍然只改变了其中带有大写字母的属性。原本带有下划线的_ageOfDeveloper和email_of_developer并不受影响！如果你需要一个更严格的策略，你可以实现自己的逻辑，一会再介绍。但在进入自定义策略前，还有最后两个预定义的策略。

字段命名策略 - UPPER_CAMEL_CASE

第四个策略是UPPER_CAMEL_CASE，它会让第一个字母大写。现在你应该迫不及待使用GsonBuilder应用命名策略:

GsonBuilder gsonBuilder = new GsonBuilder();  
gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE);  
Gson gson = gsonBuilder.create();

UserNaming user = new UserNaming("Norman", "norman@futurestud.io", true, 26);  
String usersJson = gson.toJson(user);

1
2
3
4
5
6
7

usersJson的结果是：

{
  "Name": "Norman",
  "_AgeOfDeveloper": 26,
  "Email_of_developer": "norman@futurestud.io",
  "IsDeveloper": true
}

1
2
3
4
5
6
7

你应该发现，这是第一个影响所有属性的策略。它改变了所有字段，让他们以一个大写字母开头，即使以_开头的也会改变后面的字母。这个策略不会改变分隔符，保留下划线不动。下一节介绍的会对分隔符有所改变。

字段命名策略 - UPPER_CAMEL_CASE_WITH_SPACES

最后一个命名策略UPPER_CAMEL_CASE_WITH_SPACES几乎是跟UPPER_CAMEL_CASE一样的。代码也差不多：

GsonBuilder gsonBuilder = new GsonBuilder();  
gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE_WITH_SPACES);  
Gson gson = gsonBuilder.create();

UserNaming user = new UserNaming("Norman", "norman@futurestud.io", true, 26);  
String usersJson = gson.toJson(user);  

1
2
3
4
5
6
7

来看看usersJson的结果:

{
  "Name": "Norman",
  "_Age Of Developer": 26,
  "Email_of_developer": "norman@futurestud.io",
  "Is Developer": true
}
1
2
3
4
5
6

如你所见，跟UPPER_CAMEL_CASE比起来，并没有太多区别。唯一的区别是两个字段，变成了大写字母开头，并以空格隔开。

@SerializedName的交互

可能你会好奇，怎样用@SerializedName影响策略。我们已经在之前的文章中展示过如何使用@SerializedName。让我们改变我们的UserNaming去利用@SerializedName：

public class UserNaming {  
    String Name;

    @SerializedName("emailOfDeveloper")
    String email_of_developer;

    boolean isDeveloper;
    int _ageOfDeveloper;
}
1
2
3
4
5
6
7
8
9

当你应用了上面的策略，发生了什么？答案是它会让带有@SerializedName标记的字段不受影响。比如：如果我们使用UPPER_CAMEL_CASE，生成的JSON会是这样：

{
  "Name": "Norman",
  "_AgeOfDeveloper": 26,
  "emailOfDeveloper": "norman@futurestud.io",
  "IsDeveloper": true
}
1
2
3
4
5
6

emailOfDeveloper仍然保留了在@SerializedName声明的地方的样式，没有进行首字母大写转换。

自定义字段命名

已经提供的策略跟@SerializedName结合在一起，也可能不满足你的使用需求。你可以实现自己的FieldNamingPolicy。Gson提供了第二种方法.setFieldNamingStrategy()，但你只能通过预先定义的枚举值传给.setFieldNamingPolicy()方法。

你可以传递一个FieldNamingStrategy的实例到合适的方法。FieldNamingStrategy类只有一个方法。 例如，如果我们想要移除所有的下划线，没有一个预定义的策略可以使用，我们可以使用下面的代码段：

FieldNamingStrategy customPolicy = new FieldNamingStrategy() {  
    @Override
    public String translateName(Field f) {
        return f.getName().replace("_", "");
    }
};

GsonBuilder gsonBuilder = new GsonBuilder();  
gsonBuilder.setFieldNamingStrategy(customPolicy);  
Gson gson = gsonBuilder.create();

UserNaming user = new UserNaming("Norman", "norman@futurestud.io", true, 26);  
String usersJson = gson.toJson(user);  
1
2
3
4
5
6
7
8
9
10
11
12
13

返回的JSON不会包含任何下划线：

{
  "Name": "Norman",
  "ageOfDeveloper": 26,
  "emailOfDeveloper": "norman@futurestud.io",
  "isDeveloper": true
}
1
2
3
4
5
6

Gson只会接受一个策略。这样，你可以在一个FieldNamingStrategy里实现自己的逻辑。如果你多次调用介绍给你的方法，后面的会替换前面的。

反序列化

本文只介绍了序列化的东西。换句话说，我们展示了各种使用Gson将数据从Java对象转换成JSON后的样子。所有的命名策略对于反序列化都有一样的效果。如果你有一个API，它会返回只有小写字母和下划线作为字符分开的，你可以使用LOWER_CASE_WITH_UNDERSCORES作为策略，然后你可以在你的模型里获得常规的Java命名转换。

作为一个简单的例子，如果你有下面的JSON：

{
  "reviewer_name": "Marcus"
}
1
2
3

你可以生成下面的模型：

public class PostReviewer {  
    String reviewerName;
}
1
2
3

如果你采用了正确的命名策略，即使名字不一样，Gson也会执行映射。

展望

本文中，你已经学习了使用GsonBuilder的基本知识。我们研究了第一个选项来自定义Gson的行为。特别地，我们展示了（反）序列化Java对象中的许多策略去自定义属性名称。

Gson gson = new GsonBuilder().setDateFormat(“yyyy-MM-dd HH:mm:ss”).create()

在Java中处理JSON格式的数据时，Google Gson 是个不错的选择，用起来挺方便的，也有一定灵活性。我现在工作中在参与的两个项目里都有用它。不过它在处理Date格式时有个小陷阱，在不同环境中部署时可能会遇到问题。

Gson默认处理Date对象的序列化/反序列化是通过一个SimpleDateFormat对象来实现的，通过下面的代码去获取实例：

DateFormat.getDateTimeInstance()  
1

在不同的locale环境中，这样获取到的SimpleDateFormat的模式字符串会不一样。
例如说，在我的开发机是Windows XP SP3，zh_CN.GBK，模式字符串是：

"yyyy-M-d H:mm:ss"  
1

而在我们的一台测试服务器上，RHEL 5.4，en_US.UTF-8，模式字符串则是：

"MMM d, yyyy h:mm:ss a"  
1

这就使得同样的Date对象通过Gson来序列化为JSON后内容不同。例如说要序列化的日期是2022-08-19 16:13:57，那么在我的开发机上得到的是：

"2022-8-19 16:13:57"  
1

而在那台测试服务器上则是：

"Aug 19, 2022 4:13:57 PM"  
1

这就……郁闷了。在一边序列化的内容在另一边会反序列化失败。

为了避免使用Gson时遇到locale影响Date格式的问题，使用GsonBuilder来创建Gson对象，在创建过程中调用GsonBuilder.setDateFormat(String)指定一个固定的格式即可。例如：

Gson gson = new GsonBuilder()  
  .setDateFormat("yyyy-MM-dd HH:mm:ss")  
  .create();  
1
2
3