Gson 用户指南翻译自Gson User Guide

时间 2019-11-17

标签 gson 用户指南翻译 user guide 繁體版

原文原文链接

原文:github.com/google/gson…html

概况

Gson是一个Java库，它能够用来把Java对象转换为JSON表达式，也能够反过来把JSON字符串转换成与之相同的Java对象 Gson能够对任何Java对象使用包括那些你没有源码但已存在的对象java

Gson的目标

提供简单易用的机制相似于toString()和构造器（工厂模式）用来进行Java和JSON互相转换
容许把预先存在但没法修改的对象转换为JSON或从JSON转换
容许对象的自定义表示
支持任何复杂的对象
生成紧凑易读的JSON输出

Gson的性能和可延展性

这里提供的一些参数是从咱们的笔记本（双核AMD皓龙处理器，8GB RAM，64位Ubuntu系统）上运行了不少的测试用例中获取的，你也能够用PerformanceTest类来从新运行这些测试案例git

对于字符串：反序列化超过25MB的字符串没有任何问题（能够查看PerformanceTest下的方法disabled_testStringDeserializationPerformance)github
对于大型集合：json
- 序列化过一个拥有1400万个对象的集合（能够查看PerformanceTest下的disabled_testLargeCollectionSerialization方法） -反序列化过一个拥有8.7万个对象的集合（能够查看PerformanceTest下的disabled_testLargeCollectionDeserialization方法）
Gson的1.4版本将字节数组和集合的反序列化最大值从80KB提升到了11MBapi

提示：运行这些测试用例时要删除disabled_前缀，咱们使用这些前缀是为了在每次运行JUnit测试时避免运行到上述例子数组

Gson的用户

Gson本来是创造给Google内部人员使用并运用在目前的的不少Google项目中。如今被不少公共项目和公司所使用安全

使用Gson

Gson的主要用到的类是Gson，你能够直接经过调用new Gson()来生成，也能够用类GsonBuilder来建立Gson实例进行自主的进行相似于版本控制的参数设置bash

Gson实例不会保留任何状态当你调用Json操做时，因此你能够随意的重用一个对象操做多个Json序列化和反序列化操做maven

Android：在Gradle上使用Gson

dependencies {
    implementation 'com.google.code.gson:gson:2.8.5'
}
复制代码

在Maven上使用Gson

要在Maven2/3中使用Gson，你能够在Maven库中找到Gson合适的版本添加到下面的dependency

<dependencies>
    <!--  Gson: Java to Json conversion -->
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.8.5</version>
      <scope>compile</scope>
    </dependency>
</dependencies>
复制代码

这样你的maven项目就能够用Gson了

基本例子

// 序列化
Gson gson = new Gson();
gson.toJson(1);            // ==> 1
gson.toJson("abcd");       // ==> "abcd"
gson.toJson(new Long(10)); // ==> 10
int[] values = { 1 };
gson.toJson(values);       // ==> [1]

// 反序列化
int one = gson.fromJson("1", int.class);
Integer one = gson.fromJson("1", Integer.class);
Long one = gson.fromJson("1", Long.class);
Boolean false = gson.fromJson("false", Boolean.class);
String str = gson.fromJson("\"abc\"", String.class);
String[] anotherStr = gson.fromJson("[\"abc\"]", String[].class);
复制代码

关于对象的例子

class BagOfPrimitives {
  private int value1 = 1;
  private String value2 = "abc";
  private transient int value3 = 3;
  BagOfPrimitives() {
    // 无参的构造方法
  }
}

// 序列化
BagOfPrimitives obj = new BagOfPrimitives();
Gson gson = new Gson();
String json = gson.toJson(obj);  

// ==> json is {"value1":1,"value2":"abc"}
复制代码

注意你不能序列化有循环调用的对象，否则会返回一个无限递归的结果

// 反序列化
BagOfPrimitives obj2 = gson.fromJson(json, BagOfPrimitives.class);
// ==> obj2 is just like obj
复制代码

对象的细节

对象里使用private是彻底能够运行的，并且咱们推荐你这么作
不须要声明什么区域须要被序列化或者反序列化，当前类的全部区域（包括全部的超类）都被默认包括进去
若是字段被标记为瞬态，（默认状况下）会被忽略不会被包括在JSON序列化或者反序列化中
这实现这么处理的Null值
- 序列化时，输出中省略了Null字段。
- 当反序列化时，当类中的区域在JSON结果中找不到时默认会设置：对象会设置为null，数字类型会设置为0，布尔类型会设置为false
若是类型是syntactic，会被忽略，不被包含在JSON序列化或反序列化
与内部类，匿名类和本地类中的外部类对应的字段将被忽略，而且不包括在序列化或反序列化中。

嵌套类（包含内部类）

Gson能够很容易的序列化静态嵌套类

Gson 还能够反序列化静态嵌套类。可是，Gson 不能自动反序列化纯内部类，由于它们的无参构造函数也须要引用包含的可是还没被反序列化的对象。您能够经过使内部类变为静态内部类或为其提供自定义 InstanceCreator 来解决此问题这是一个例子：

public class A { 
  public String a; 

  class B { 

    public String b; 

    public B() {
      // B的无参构造函数
    }
  } 
}
复制代码

注意：上述 B 类不能（默认状况下）使用 Gson 序列化。

{"b":"abc"}因为 B 类是一个内部类，Gson 不能反序列化为 B 的实例。若是它被定义为静态类 B，那么 Gson 就可以反序列化字符串。另外一种解决方案是为 B 编写自定义实例建立器。

public class InstanceCreatorForB implements InstanceCreator<A.B> {
  private final A a;
  public InstanceCreatorForB(A a)  {
    this.a = a;
  }
  public A.B createInstance(Type type) {
    return a.new B();
  }
}
复制代码

上述代码能够运行可是不推荐

关于数组的例子

Gson gson = new Gson();
int[] ints = {1, 2, 3, 4, 5};
String[] strings = {"abc", "def", "ghi"};

// Serialization
gson.toJson(ints);     // ==> [1,2,3,4,5]
gson.toJson(strings);  // ==> ["abc", "def", "ghi"]

// Deserialization
int[] ints2 = gson.fromJson("[1,2,3,4,5]", int[].class); 
// ==> ints2 will be same as ints
复制代码

咱们也支持多尺寸数组和任何复杂的元素类型

集合例子

Gson gson = new Gson();
Collection<Integer> ints = Lists.immutableList(1,2,3,4,5);

// Serialization
String json = gson.toJson(ints);  // ==> json is [1,2,3,4,5]

// Deserialization
Type collectionType = new TypeToken<Collection<Integer>>(){}.getType();
Collection<Integer> ints2 = gson.fromJson(json, collectionType);
// ==> ints2 is same as int
复制代码

可怕的现象：注意到咱们怎么定义collection类型的吗？不幸的是，在Java里不能这么作

集合的限制： Gson能够序列化任意对象的集合，但不能从中反序列化，由于用户没法知道结果对象的类型。相反，在反序列化时，集合必须是特定的泛型类型。你们都知道，当遵循良好的编码习惯就不多出现问题

当序列化和反序列化泛型

当你调用toJson(obj)，Gson会调用obj.getClass()来获取区域的信息去序列化，一样，你能够经过MyClass.class对象的fromJson(json, MyClass.class)方法.若是对象里没有泛型这么作也能够。可是，若是你的对象里有泛型，这么作泛型会丢失，由于Java的类型擦除，这有个例子来讲明这点

class Foo<T> {
  T value;
}
Gson gson = new Gson();
Foo<Bar> foo = new Foo<Bar>();
gson.toJson(foo); // 这样可能没法正确的序列化 foo.value 

gson.fromJson(json, foo.getClass()); // 没法把 foo.value 做为 Bar 反序列化
复制代码

上述代码想赋予value的类型Bar但失败了由于Gson调用了list.getClass()方法去获取这个类的信息，可是返回一个纯类Foo.class。这就是说Gson没有方法知道你的对象的类型是Foo<Bar>而不是Foo。

你能够经过肯定正确的参数来代替泛型能够解决上述问题，你也能够用TypeToken类

Type fooType = new TypeToken<Foo<Bar>>() {}.getType();
gson.toJson(foo, fooType);

gson.fromJson(json, fooType);
复制代码

惯用方法是获取fooType来实际定义一个匿名内部类来包含用来返回整个参数类型的getType()方法

序列化和反序列化带有任意类型对象的集合

有时候你须要处理带有杂乱类型的JSON数组，像是['hello',5,{name:'GREETINGS',source:'guest'}] 与之相等的Collection包含：

Collection collection = new ArrayList();
collection.add("hello");
collection.add(5);
collection.add(new Event("GREETINGS", "guest"));
复制代码

类Event定义成：

class Event {
  private String name;
  private String source;
  private Event(String name, String source) {
    this.name = name;
    this.source = source;
  }
}
复制代码

你能够直接用Gson去序列化集合并且不用作其余任何事情，toJson(collection)会写出你期待的输出

可是，反序列化fromJson(json, Collection.class)没法工做，由于 Gson 没法知道如何将输入映射到类型。Gson 要求您提供集合类型的通用版本fromJson()。因此，你有三个选择：

使用 Gson 的解析器 API（低级流解析器或 DOM 解析器 JsonParser）来解析数组元素，而后Gson.fromJson()在每一个数组元素上使用。这是首选方法。这是一个演示如何执行此操做的示例
注册一个类型适配器Collection.class，查看每一个数组成员并将它们映射到适当的对象。这种方法的缺点是它会搞砸 Gson 中其余集合类型的反序列化。
注册一个类型的适配器MyCollectionMemberType，并使用fromJson()与Collection<MyCollectionMemberType>。

仅当数组显示为顶级元素或者您能够更改将集合保持为类型的字段类型时，此方法才可用Collection<MyCollectionMemberType>。

内置的序列化器和反序列化器

Gson 有经常使用类的内置序列化器和反序列化器，其默认表示可能不合适。如下是此类的列表：

java.net.URL 把它与字符串匹配 "https://github.com/google/gson/"
java.net.URI 把它与字符串匹配 "/google/gson/"

您还能够在此页面找到一些经常使用类的源代码，例如 JodaTime 。

自定义序列化和反序列化

有时默认表示不是您想要的。处理库类（DateTime 等）时常常会出现这种状况。Gson 容许您注册本身的自定义序列化程序和反序列化程序。这是经过定义两部分来完成的：

Json Serializers：须要为对象定义自定义序列化
Json Deserializers：须要为类型定义自定义反序列化
Instance Creators：若是无参构造函数可用或注册了反序列化器，则不须要

GsonBuilder gson = new GsonBuilder();
gson.registerTypeAdapter(MyType2.class, new MyTypeAdapter());
gson.registerTypeAdapter(MyType.class, new MySerializer());
gson.registerTypeAdapter(MyType.class, new MyDeserializer());
gson.registerTypeAdapter(MyType.class, new MyInstanceCreator());
复制代码

registerTypeAdapter 调用检查类型适配器是否实现了多个这些接口并为全部接口注册它。

编写Json Serializers

如下是如何为 JodaTime DateTime类编写自定义序列化程序的示例。

private class DateTimeSerializer implements JsonSerializer<DateTime> {
  public JsonElement serialize(DateTime src, Type typeOfSrc, JsonSerializationContext context) {
    return new JsonPrimitive(src.toString());
  }
}
复制代码

Gson在序列化过程当中遇到DateTime对象时调用serialize()。

编写Json Deserializers

下面是如何为JodaTime DateTime类编写自定义反序列化器的示例。

private class DateTimeDeserializer implements JsonDeserializer<DateTime> {
  public DateTime deserialize(JsonElement json, Type typeOfT, JsonDeserializationContext context)
      throws JsonParseException {
    return new DateTime(json.getAsJsonPrimitive().getAsString());
  }
}
复制代码

当须要将JSON字符串片断反序列化为DateTime对象时，Gson调用deserialize

序列化器和反序列化器的细节

一般，您但愿为与原始类型对应的全部泛型类型注册单个处理程序

例如，假设您有一个Id用于 id 表示 / 转换的类（即内部表示与外部表示）。
Id<T> 对全部泛型类型具备相同序列化的类型
- 基本上写出 id 值
反序列化很是类似但不彻底相同
- 须要调用new Id(Class<T>, String)哪一个返回一个实例Id<T>

Gson 支持为此注册一个处理程序。您还能够为特定的泛型类型注册特定的处理程序（好比Id<RequiresSpecialHandling>须要特殊处理）。在Type该参数toJson()和fromJson()包含的通用类型的信息来帮助你编写对应于同一原始类型的全部泛型类型单一的处理程序。

编写Instance Creators

在反序列化 Object 时，Gson 须要建立该类的默认实例。用于序列化和反序列化的良好的类应该具备无参数构造函数。

与用public仍是private无关

一般，在处理未定义无参数构造函数的库类时，须要实例建立器

Instance Creators示例

private class MoneyInstanceCreator implements InstanceCreator<Money> {
  public Money createInstance(Type type) {
    return new Money("1000000", CurrencyCode.USD);
  }
}
复制代码

类型能够是相应的泛型类型

对于调用须要特定泛型类型信息的构造函数很是有用
例如，若是Id类存储了正在为其建立 Id 的类

参数化类型的 InstanceCreator

有时，您尝试实例化的类型是参数化类型。一般，这不是问题，由于实际的实例是原始类型。这是一个例子：

class MyList<T> extends ArrayList<T> {
}

class MyListInstanceCreator implements InstanceCreator<MyList<?>> {
    @SuppressWarnings("unchecked")
  public MyList<?> createInstance(Type type) {
    // No need to use a parameterized list since the actual instance will have the raw type anyway.
    return new MyList();
  }
}
复制代码

可是，有时您须要根据实际参数化类型建立实例。在这种状况下，您可使用传递给createInstance方法的 type 参数。这是一个例子：

public class Id<T> {
  private final Class<T> classOfId;
  private final long value;
  public Id(Class<T> classOfId, long value) {
    this.classOfId = classOfId;
    this.value = value;
  }
}

class IdInstanceCreator implements InstanceCreator<Id<?>> {
  public Id<?> createInstance(Type type) {
    Type[] typeParameters = ((ParameterizedType)type).getActualTypeArguments();
    Type idType = typeParameters[0]; // Id has only one parameterized type T
    return Id.get((Class)idType, 0L);
  }
}
复制代码

在上面的示例中，若是没有实际传入参数化类型的实际类型，则没法建立 Id 类的实例。咱们经过使用传递的方法参数来解决这个问题type。type在这种状况下，对象是 Java 参数化类型表示Id<Foo>实际实例应绑定到的位置Id<Foo>。因为Idclass 只有一个参数化类型参数，T咱们使用返回的类型数组的第 0 个元素，在这种状况下getActualTypeArgument()它将保存Foo.class。

JSON输出形式：紧凑输出VS优雅输出

Gson 提供的默认 JSON 输出是紧凑的 JSON 格式。这意味着输出 JSON 结构中不会有任何空格。所以，JSON 输出中的字段名称及其值，对象字段和数组内的对象之间不会有空格。一样，输出中将忽略 “null” 字段（注意：null 值仍将包含在对象的集合 / 数组中）。有关配置 Gson 以输出全部空值的信息，请参阅Null 对象支持部分。

若是要使用 “优雅输出” 功能，则必须使用GsonBuilder来建立Gson实例。JsonFormatter没有在咱们的公共 API 公开，因此用户没法为JSON的输出形式作配置和调整，目前，咱们只提供JsonPrintFormatter默认行长度为 80 个字符，2 个字符缩进和 4 个字符右边距。

如下是一个示例，说明如何配置Gson实例以使用默认值JsonPrintFormatter而不是JsonCompactFormatter：

Gson gson = new GsonBuilder().setPrettyPrinting().create();
String jsonOutput = gson.toJson(someObject);
复制代码

空对象支持在 Gson 中实现的默认行为null是忽略对象字段。这容许更紧凑的输出格式；可是，用户必须为这些字段定义默认值，由于 JSON 格式将转换回其 Java 表单。

如下是配置Gson实例输出 null 的方法：

Gson gson = new GsonBuilder().serializeNulls().create();
复制代码

注意：在使用 Gson 序列化 null 时，它会向JsonElement结构添加JsonNull元素。所以，此对象可用于自定义序列化 / 反序列化。

这是一个例子：

public class Foo {
  private final String s;
  private final int i;

  public Foo() {
    this(null, 5);
  }

  public Foo(String s, int i) {
    this.s = s;
    this.i = i;
  }
}

Gson gson = new GsonBuilder().serializeNulls().create();
Foo foo = new Foo();
String json = gson.toJson(foo);
System.out.println(json);

json = gson.toJson(null);
System.out.println(json);
复制代码

输出是：

{"s":null,"i":5}
null
复制代码

版本控制支持

使用@Since注释能够维护同一对象的多个版本。此批注可用于类，字段以及未来的发行版中的方法。要利用此功能，必须将Gson实例配置为忽略任何大于某个版本号的字段 / 对象。若是没有在Gson实例上设置任何版本，则不管版本如何，它都将序列化和反序列化全部字段和类。

public class VersionedClass {
  @Since(1.1) private final String newerField;
  @Since(1.0) private final String newField;
  private final String field;

  public VersionedClass() {
    this.newerField = "newer";
    this.newField = "new";
    this.field = "old";
  }
}

VersionedClass versionedObject = new VersionedClass();
Gson gson = new GsonBuilder().setVersion(1.0).create();
String jsonOutput = gson.toJson(someObject);
System.out.println(jsonOutput);
System.out.println();

gson = new Gson();
jsonOutput = gson.toJson(someObject);
System.out.println(jsonOutput);
复制代码

输出是：

{"newField":"new","field":"old"}
复制代码

从序列化和反序列化中排除字段

Gson 支持许多排除顶级类，字段和字段类型的机制。下面列出的是可插入的机制，容许字段和类排除。若是如下机制都不能知足您的需求，那么您始终可使用自定义序列化程序和反序列化程序。

Java 修饰符排除

默认状况下，若是将字段标记为transient，则将排除该字段。一样，若是某个字段被标记为static默认状况下将被排除。若是要包含一些瞬态字段，则能够执行如下操做：

import java.lang.reflect.Modifier;
Gson gson = new GsonBuilder()
    .excludeFieldsWithModifiers(Modifier.STATIC)
    .create();
复制代码

注意：您能够为方法excludeFieldsWithModifiers提供任意数量的Modifier常量。例如：

Gson gson = new GsonBuilder()
    .excludeFieldsWithModifiers(Modifier.STATIC, Modifier.TRANSIENT, Modifier.VOLATILE)
    .create();
复制代码

GSON 的 `@Expose`

此功能提供了一种方法，您能够将要排除的对象的某些字段标记为序列化和反序列化为 JSON。要使用此批注，必须使用建立 Gson new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create()。建立的 Gson 实例将排除类中未标注@Expose注释的全部字段。

用户定义的排除策略

若是排除字段和类类型的上述机制对您不起做用，那么您始终能够编写本身的排除策略并将其插入 Gson。有关ExclusionStrategy更多信息，请参阅 JavaDoc。

如下示例显示如何排除标记有特定@Foo注释的字段，并排除类的顶级类型（或声明的字段类型）String。

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})
public @interface Foo {
  // Field tag only annotation
}

public class SampleObjectForTest {
  @Foo private final int annotatedField;
  private final String stringField;
  private final long longField;
  private final Class<?> clazzField;

  public SampleObjectForTest() {
    annotatedField = 5;
    stringField = "someDefaultValue";
    longField = 1234;
  }
}

public class MyExclusionStrategy implements ExclusionStrategy {
  private final Class<?> typeToSkip;

  private MyExclusionStrategy(Class<?> typeToSkip) {
    this.typeToSkip = typeToSkip;
  }

  public boolean shouldSkipClass(Class<?> clazz) {
    return (clazz == typeToSkip);
  }

  public boolean shouldSkipField(FieldAttributes f) {
    return f.getAnnotation(Foo.class) != null;
  }
}

public static void main(String[] args) {
  Gson gson = new GsonBuilder()
      .setExclusionStrategies(new MyExclusionStrategy(String.class))
      .serializeNulls()
      .create();
  SampleObjectForTest src = new SampleObjectForTest();
  String json = gson.toJson(src);
  System.out.println(json);
}
复制代码

输出是：

{"longField":1234}
复制代码

JSON 字段命名支持

Gson 支持一些预约义的字段命名策略，以将标准 Java 字段名称（即以小写字母 --- 开头的驼峰名称sampleFieldNameInJava）转换为 Json 字段名称（即sample_field_name_in_java或SampleFieldNameInJava）。有关预约义命名策略的信息，请参阅FieldNamingPolicy类。

它还具备基于注释的策略，容许用户基于每一个字段定义自定义名称。请注意，基于注释的策略具备字段名称验证，若是提供了无效的字段名称做为注释值，则会引起 “运行时” 异常。

如下是如何使用两个 Gson 命名策略功能的示例：

private class SomeObject {
  @SerializedName("custom_naming") private final String someField;
  private final String someOtherField;

  public SomeObject(String a, String b) {
    this.someField = a;
    this.someOtherField = b;
  }
}

SomeObject someObject = new SomeObject("first", "second");
Gson gson = new GsonBuilder().setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE).create();
String jsonRepresentation = gson.toJson(someObject);
System.out.println(jsonRepresentation);
复制代码

输出是：

{"custom_naming":"first","SomeOtherField":"second"}
复制代码

若是您须要自定义命名策略（请参阅此讨论），可使用@SerializedName的注解。

在自定义序列化器和反序列化器之间共享状态

有时您须要在自定义序列化器 / 反序列化器之间共享状态（请参阅此讨论）。您可使用如下三种策略来完成此任务：

在静态字段中存储共享状态
将序列化器 / 反序列化器声明为父类型的内部类，并使用父类型的实例字段来存储共享状态
使用 Java ThreadLocal

1 和 2 不是线程安全选项，但 3 是。

流

除了 Gson 的对象模型和数据绑定以外，您还可使用 Gson 读取和写入流。您还能够组合流和对象模型访问，以得到两种方法中的最佳方法。

在设计 Gson 时遇到的问题

有关咱们在设计 Gson 时遇到的问题的讨论，请参阅Gson 设计文档。它还包括 Gson 与可用于 Json 转换的其余 Java 库的比较。

Gson 将来的改进

有关最新的更新计划或者若是你有新的建议，请参阅项目网站下的 Issues。部分

Gson 用户指南 翻译自Gson User Guide

概况

Gson的目标

Gson的性能和可延展性

Gson的用户

使用Gson

Android：在Gradle上使用Gson

在Maven上使用Gson

基本例子

关于对象的例子

对象的细节

嵌套类（包含内部类）

关于数组的例子

集合例子

当序列化和反序列化泛型

序列化和反序列化带有任意类型对象的集合

内置的序列化器和反序列化器

自定义序列化和反序列化

编写Json Serializers

编写Json Deserializers

编写Instance Creators

参数化类型的 InstanceCreator

JSON输出形式：紧凑输出VS优雅输出

版本控制支持

从序列化和反序列化中排除字段

Java 修饰符排除

GSON 的 @Expose

用户定义的排除策略

JSON 字段命名支持

在自定义序列化器和反序列化器之间共享状态

流

在设计 Gson 时遇到的问题

Gson 将来的改进

Gson 用户指南翻译自Gson User Guide

GSON 的 `@Expose`