Gson Builder — 基础& 命名策略

原文链接：Gson Builder — Basics & Naming Policies

作者：Norman Peitek

翻译：签到钱就到

在该系列的前面的文章中，你已经学会了如何使用Gson去将java对象转换成JSON，反之亦然。目前为止，我们已经展示了如何建立模型，以及为了得到正确的映射，哪些需要重点关注。这篇文章，我们将开始本系列的一个新的文集，这一部分将使用GsonBuilder定制Gson部分模块的行为。

当然，这不是Gson系列的唯一一篇，如果你对其他文章也感兴趣，浏览一下下面的大纲：

Gson系列概览

1. 用java-JSON实现序列化合反序列化
2. 嵌套对象的映射
3. Mapping of Arrays and Lists of Objects
4. Mapping of Maps
5. Mapping of Sets
6. Mapping of Null Values
7. Gson Model Annotations — How to Ignore Fields with @Expose
8. Gson Model Annotations — How to Change the Naming of Fields with @SerializedName
9. Gson Builder — Basics & Naming Policies
10. Gson Builder — Force Serialization of null Values
11. Gson Builder — Exclusion Strategies
12. Gson Builder — Relax Gson with Lenient
13. Gson Builder — Special Values of Floats & Doubles
14. Gson Builder — Model Versioning
15. Gson Builder — Formatting of Dates & Custom Date/Time Mapping
16. Gson Builder — Pretty Printing
17. Gson Builder — HTML Escaping

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();  

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;
}

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

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

所有使用上述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);  

usersJson会包含：

{
  "Name": "Norman",
  "_ageOfDeveloper": 26,
  "email_of_developer": "norman@futurestud.io",
  "isDeveloper": true
}

如你所见，没有一个字段的命名被改变了。名字是从模型中原封不动地拷贝过来。如果你没有设置命名策略或者没有使用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); 

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

{
  "name": "Norman",
  "_age_of_developer": 26,
  "email_of_developer": "norman@futurestud.io",
  "is_developer": true
}

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);  

生成一个新的uersJson，如下：

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

请注意，仍然只改变了其中带有大写字母的属性。原本带有下划线的_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);

usersJson的结果是：

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

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

字段命名策略 - 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);  

来看看usersJson的结果:

{
  "Name": "Norman",
  "_Age Of Developer": 26,
  "Email_of_developer": "norman@futurestud.io",
  "Is Developer": true
}

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

@SerializedName的交互

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

public class UserNaming {  
    String Name;

    @SerializedName("emailOfDeveloper")
    String email_of_developer;

    boolean isDeveloper;
    int _ageOfDeveloper;
}

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

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

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);  

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

{
  "Name": "Norman",
  "ageOfDeveloper": 26,
  "emailOfDeveloper": "norman@futurestud.io",
  "isDeveloper": true
}

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

反序列化

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

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

{
  "reviewer_name": "Marcus"
}

你可以生成下面的模型：

public class PostReviewer {  
    String reviewerName;
}

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

展望

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

下篇文章，我们将会继续展示更多的GsonBuilder能力。特别地，我们会介绍强制Gson去序列化null值。

如果你有需要反馈的或疑问，在下面的评论中让我们知道，或者twitter@futurestud_io。

尽情享受代码带来的快乐！！！