Gson 中文翻译

Gson2.8.5文档翻译
文档
API Javadoc :当前版本的文档。
用户向导：该向导包含你的代码中如何使用Gson的案例。
改动日志：最近版本的变化。
设计文档：这个文档讨论了当设计Gson时候面对的问题。他也包含Gson和其他Java他用于json转化的类库的比较。
请使用StackOverflow上的’gson’标签或goole-gson Google group 去讨论Gson或者发布问题。

Gson用户指南
1,概览
2，Gson的目标
3，Gson性能和可伸缩性
4，Gson用户
5，使用Gson
在Gradle/Android中使用Gson
在Maven中使用Gson
原始实例
对象实例
对象细节
嵌套类（包括内部类）
数组实例
集合实例
*集合限制
序列化和反序列化泛型
序列化和反序列化任一类型的对象的集合
内置的序列化和反序列化器
自定义的序列化和反序列化
*编写序列化器
*编写反序列化器
编写Creator实例
*参数化类型的Creator实例
支持Null对象
版本支持
序列化和反序列化中排除字段
*Java Modifier 排除
*Gson的@Expose
*用户自定义排除策略
JSON字段命名支持
跨自定义序列化器和反序列化器分享状态
Streaming
6，设计Gson时的问题
7，Gson未来的增强

概览
Gson是一个用于把一个Java对象转化为他们的JSON表示的java类库。他也能用于把JSON字符串转为一个等效的Java对象。Gson可以处理任意的Java对象，包括你没有源码的提前存在的对象。
有些开源的项目也是可以把Java对象转为JSON,然而，大部分必须在你的Java类上使用注解；如果有时候你不能去访问源码，你就不能这么做了。大部分时候也不能对Java的泛型有完整的支持。Gson认为这些都是非常重要的设计目标。

Gson的目标
提供简单的toJson()和fromJson()方法把Java对象转化为JSON和把JSON对象转为Java对象。
允许将与现存在的，不可修改的对象转化为JSON和把JSON转化为Java对象。
对Java泛型有广泛的支持。
允许对象的自定义表示。
支持任意的复杂对象（具有深度继承体系且广泛使用泛型）。

Gson的性能和可伸缩性
这有一些我们在一个测试运行许多事情的桌面上获取的一些指标（多核心，8GB RAM,64-bit Ubuntu）。你可以使用PerformanceTest类重新进行测试。
Strings:反序列化大于250MB的字符串不会有任何问题。
大型集合：
序列化140万个对象的集合（查看PerformanceTest中的disabled_testLargeCollectionSerialization方法）
反序列化包含87000对象的一个集合（查看PerformanceTest中的disable_testLargeCollectionDeserialzation）
注意：删除disable_前缀去运行这些测试。我们使用这个前缀来防止运行JUNIT测试时每次都运行这些测试。

Gson用户
Gson最初创建出来是为了在Goole内部中使用的，目前已经在很多的项目中使用了。他现在被许多的公开项目和公司使用。

使用Gson
去使用的主要的类是Gson，你可以调用new Gson()来调用。还有另外一个GsonBuilder类可以用于创建一个有多个设置如版本控制等的Gson实例。
当调用Json运行时，Gson实例不能维护任何状态。因此，您可以在多个Json序列化和反序列化运行时重复调用一样的对象。
在gradle/android中使用Gson

在Maven中使用Gson
要在Maven2/3中使用Gson,您可以在Maven Central中添加如下的依赖使用可以用的Gson版本。
从Maven Central下载可用的Gson jar。
就是这样，现在你的maven项目中启用了Gson。

原始案例
（序列化与反序列化）

对象案例

注意，你不要循环引用序列化对象，这样的结果将是无限递归。

对象的细节
最好使用（而且也是推荐的）private字段。
不需要使用任何一个注解去指示序列化和反序列化包含的字段。当前类中的所有字段都是默认包含的（以及所有来自于父类的字段）。
如果一个字段标记为transient,(默认的)那么他在JSON序列化或反序列化中中是忽略的，未包含的。
这个实现正确的处理null。
当序列化时，一个null字段在输出时是被删除的。
当反序列化化时，JSON结果中缺少一个记录，在对象中相关的字段设置为默认值：对象类型为null,数字类型为0,布尔类型为false。
如果一个字段是复合字段（嵌套类型），他是被忽略的，也不会包含在JSON的序列化或反序列化中。
在内部类，匿名类和本地类中与外部类中对应的字段将会被忽略，并且不会包含在序列化和反序列化中。

嵌套类（包含内部类）
Gson能相当容易的序列化静态嵌套类。
Gson也能反序列化静态类。然而，Gson不能自动的反序列化纯内部类，因为他们的无参构造方法也需要对包含Object的引用，因为此时的反序列化是不可用的。你可以解决通过提供静态的内部类或者提供一个自定义的创造器实例来解决这个问题。这有一个案例：

注意：上面的class B 不能（默认的）使用Gson进行序列化。
Gson不能反序列化{“b”:”abc”}到一个B实例，因为class B 是一个内部类。如果定义为静态static class B,那么Gson将能反序列化在这个字符串。另一个解决方案是编写一个自定义的B的创建者实例。

注意：以上是可以的，但是不推荐。

数组案例

我们还支持具有任意复杂元素类型的多维数组。

集合案例

相当可怕的是：注意我们怎么定义了集合的类型，不幸的是，在Java中无法绕过这个问题。

集合限制
Gson可以序列化任意对象的集合但是不能从中反序列化。因为用户无法指定结果的类型。相反，当反序列化时，集合必须是一个特定的，泛型类型。当遵循好的Java开发实践时很难出现这样的问题。

序列化和反序列化泛型类型
当你调用toJson(obj)，Gson调用obj.getClass() 去获取字段的信息以便于序列化。类似的，你可以在fromJson(json,MyClass,Class)方法中传递MyClass.class。如果对象不是一个泛型类型，这样使用是很好的。然而，如果对象是泛性类型的对象，泛型类型将会丢失，因为Java 类型擦除了。这里有一个案例来说明此点：

以上的代码在把值解析为Bar类型的时候失败了，因为Gson调用了list.getClass() 去获取类信息，但是这个方法返回了一个原始的类，Fool.class。这意味着Gson无法知道这是Foo类型的对象，因为他不仅仅是一个普通的Foo。
你可以为你的这个泛型类型提供正确的参数去解决这个问题。你可以使用TypeToken.class来解决这个问题。

这样获取fooType的方式 实际是定义了一个包含全部参数类型的getType()方法的局部匿名内部类。

使用任意类型的对象序列化和反序列化集合

有时，你在处理的JSON数组包含了复合类型。例如：
[‘hello’，5，{ name:‘GREETINGS’，source:‘guest’}]
等同于包含如下数据的一个集合：

当Event 类定义为

您可以使用Gson不做任何任何特殊的操作，就能序列化这个集合: toJson(collection);将把所需输出。
但是，无法使用fromJson(json,Collection.class)进行反序列化，因为Gson无法知道如何去映射输入到指定类型。Gson需要你在fromJson()中提供一个集合类型的通用的版本。因此，你可以有三个选择：
1，使用Gson的解析器API（底层流失解析或DOM解析JsonParser)去解析数组元素，然后在每个数据元素上使用Gson.fromJson( )。这里有一个例子去演示如何来做。
2，为Collection.class注册一个类型适配器，用来查看每一个数组元素并且把他们映射到合适的对象。这种处理的缺点是将影响Gson中其他集合类型的反序列化。
3，使用formJson()和Collection为MyCollectionMemberType注册一个类型适配器。
只有在数组作为一个顶级元素出现，或者如果你能改变字段类型为Collection这种方法才有用。

内置的序列化器和反序列化器
Gson为表示也许不合适的常用类提供了内置的序列化器和反序列化器。这里有这些类的列表：
1，java.net.URL 匹配如同”https://github.com/googe/gson”的字符串
2，java.net.URI 匹配如同”/google/gson/”的字符串
你可以在本页中从一些常用类中的训中源码，例如JodaTime。

自定义序列化和反序列化
有时候默认的表示并不是你希望的。当处理类库（DateTime等）经常出现这种情况。Gson允许你去注册你自己的自定义序列化和反序列化。这样做需要定义两部分：
1，Json序列化器：需要为一个对象定义自定义序列化
2，Json反序列化器：需要为类型定义反序列化
3，实例创建器：如果无参构造可用或注册了反序列化器，那就不需要了。

Registertypeadapter 调用检查类型适配器是否实现这些接口中的多个，并为所有接口注册它。

编写一个序列化器
这里是一个如何为JodaTime DateTime类编写的一个自定义序列化器案例。

序列化时，当运行到DateTime 对象，Gson调用 serialize( )。
编写一个反序列化器
这里是一个如何为JodaTime DateTime类编写的一个自定义反序列化器案例。

反序列化时，当运行到DateTime 对象，Gson调用 deserialize( )。

对空对象的支持
Gson中对空对象的字段默认行为是进行忽略。这样使得输出格式更简洁；然而，当Json格式转换回Java形式时，必须定义为这些字段一个默认的值。
这里是如何配置一个Gson实例去输出null：

注意：当使用Gson序列化多个null时，他将向JsonElement结构中添加一个JsonElement元素。因此，这个对象可用于自定义序列化器/反序列化器。
这里有一个案例：

输出结果是

从序列化和反序列化中排除字段
Gson支持多种方式排除顶级类，字段和字段值。以下是把允许的字段和类排出的机制。如果下面的机制无法满足你的需求，你可以使用自定义序列化器和反序列化器。
Java修饰词排除
默认情况下，如果你把一个字段标记为transient，他将会被排除。同样的，如果一个字段标记为static,那么默认的情况下也被排除，如果你想包含一些临时的字段，你可以这么做：

Gson的@Expose
这个特性提供一个方法，以便于在序列化和反序列化时你的对象中明确要排除的字段不会传成JSON。使用这个注解，你必须去使用new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create().
去创建Gson。创建的 Gson 实例将排除类中未标记为@expose 注释的所有字段。

用户自定义排除策略
如果上述排除字段和类类型的机制不适合您，那么您可以编写自己的排除策略并将其导入Gson。 更多信息请参见 ExclusionStrategy JavaDoc。
下面的示例演示如何排除标有特定@foo 注解的字段，并排除类 String 的顶级类型(或声明的String类型)。
自定义注解

输出结果是
{“longField”:1234}