Gson 是 Google 提供的用来在 Java 对象和 JSON 数据之间进行映射的 Java 类库。可以将一个 JSON 字符串转成一个 Java 对象，或者反过来。

1. 基本用法

Gson 提供了 fromJson() 和 toJson() 两个直接用于解析和生成的方法，前者实现反序列化，后者实现了序列化。

public class User {
    public String name;
    public int age;
    public String emailAddress;

    // 省略 getter/setter
}

生成 JSON 格式字符串：<small>（Object to JSON-String）</small>

Gson gson = new Gson();
User user = new User("怪盗kidou",24);
String jsonObject = gson.toJson(user); // {"name":"怪盗kidou","age":24}

解析 JSON 格式字符串：<small>（JSON-String to Object）</small>

Gson gson = new Gson();
String jsonString = "{\"name\":\"怪盗kidou\",\"age\":24}";
User user = gson.fromJson(jsonString, User.class);

@SerializedName 注解

默认/一般情况下，JSON 字段中的名字和类的属性名是一致的。但是也有不一致的情况，因为本身驼峰命名法（如 Java）和下划线命名法（如 C）本身就是两大命名规则“流派”。

对类的属性使用 @SerializedName 注解，可以重新指定与该属性对应的 JSON 字符串中的名字。

@SerializedName("email_address")
public String emailAddress;

你甚至可以重新命名为另一个看起来毫不相关的名字：

@SerializedName("xxx")
public String emailAddress;

数组的序列化和反序列化

数组的序列化和反序列化比较简单，与普通对象类似，唯一需要注意的就是填写正确的数组类型：

str = gson.toJson(arr);

arr = gson.fromJson(str, int[].class);
arr = gson.fromJson(str, String[].class);
arr = gson.fromJson(str, User[].class);

集合的序列化和反序列化

相较于数组，集合的序列化和反序列化就复杂一些，因为泛型的 类型檫除，Java “分辨”不出 List<String> 和 List<User>，对 Java 而言它们的类型都是 List.class 。

为了解决的上面的问题，Gson 为我们提供了 TypeToken 来实现对泛型的支持，所以当我们希望使用将以上的数据解析为 List<String> 时需要讲 List<String> “套在” new TypeToken<T>(){}.getType() 中。

arr = gson.fromJson(str, new TypeToken<List<User>>(){}.getType());

泛型 和 RESETfull API

泛型的引入可以减少无关的代码，这在 resetful api 返回数据时反映得更为清楚，通常 resetful api 接口返回的 Json 数据为：

{"status":0,"msg":'...',"data":{...}},
{"status":0,"msg":'...',"data":[...]},

status 表示响应状态码，msg 表示状态码配套的信息，而 data 才是最核心的部分：响应的数据。一般而言，它要么表示返回一个对象，要么表示返回一个对象的集合<small>（数组或 List）</small>。

在这里会把这个结果对象定义成泛型类：

public class Result<T> {
    public int code;
    public String message;
    public T data;
}

否则，data 的类型无穷无尽，你就需要为每一种情况定义一种 Result 类。

那么对于 data 字段，当 T 是 User 时则可以写为 Result<User>，当是个列表的时候为 Result<List<User>>，其它类型同理（Result\<XXX> 和 Result<List<XXX>>）。

对此，Json 字符串转对象时，代码自然就类似如下：

//不再重复定义Result类
Type userType = new TypeToken<Result<User>>(){}.getType();
Result<User> userResult = gson.fromJson(json,userType);
User user = userResult.data;

Type userListType = new TypeToken<Result<List<User>>>(){}.getType();
Result<List<User>> userListResult = gson.fromJson(json,userListType);
List<User> users = userListResult.data;

使用 GsonBuilder 导出 null 值、格式化输出、日期时间

显而易见，GsonBuilder 是用于构建 Gson 实例的一个类，要想改变 Gson 默认的设置必须使用该类配置 Gson 。

Gson gson = new GsonBuilder()
               //各种配置
               .create(); //生成配置好的 Gson

一个最常见的使用场景就是：导出 null 值。Gson 在默认情况下是不动导出值 null 的键的。

Gson gson = new Gson();
User user = new User("tom",20, null);
System.out.println(gson.toJson(user));
// {"name":"tom","age":24}

因其值为 null，emailAddress 字段并未出现在 JSON-String 中。这里容易造成一个困惑：单看 JSON-String，你无法知道它所表示的对象中还存在一个 emailAddress 属性。或者说，在调试时，需要生成完整的 JSON-String 以供分析查错。

对此，你可以使用 GsonBuilder 设置所生成的 Gson 对象，开启其导出 null 值的功能。

Gson gson = new GsonBuilder().serializeNulls().create();
User user = new User("tom",20, null);
System.out.println(gson.toJson(user));
// {"name":"tom","age":20,"emailAddress":null}

另一个比较常见的场景就是 Date 类型的属性 和 字符串 之间转换时的格式化。

Gson gson = new GsonBuilder()
                  .serializeNulls()
                  .setDateFormat("yyyy-MM-dd")
                  .create();

循环引用 和 @Expose 注解

在 Java 中，两个对象可能会互相持有，此时就是循环引用现象。当序列化其中一个对象时，会涉及到它的相关对象，而序列化它的相关对象时，又会再次序列化它自己，而序列化它自己时又需要去序列化它的相关对象... ...，从而造成一个死循环。

Gson 提供的 @Expose 注解可以解决循环依赖问题。被标注了 @Expose 的属性会被导出，没有标注的则不会导出。另外，@Expose 还有两个属性可以进一步细化控制序列化和反序列化行为：

@Expose // 默认值都为 true
@Expose(deserialize = true, serialize = true) // 序列化、反序列化都生效
@Expose(deserialize = true, serialize = false) // 序列化时忽略该属性
@Expose(deserialize = false, serialize = true) // 反序列化时忽略该属性
@Expose(deserialize = false, serialize = false) // 序列化、反序列化时都忽略该属性

注意，@Expose 注解需要配合 GsonBuilder 使用：

Gson gson = new GsonBuilder()
              .excludeFieldsWithoutExposeAnnotation()
              .create();

补充，还有其他的办法能解决循环引用问题，但是 @Expose 是最常见方案。

POJO 与 JSON 的字段映射规则

之前提到过这样的场景，如果提供 JSON-String 的人和使用（反序列化）JSON-String 的人是两个不同的人，那么就无法保证 JSON-String 中的字段名和类的属性名一定一致。当然，如前面所说，对于这个问题，可以通过使用 @SerializedNam 注解决绝。

除此之外，对于常见的“不一致”的情况，Gson 提供了统一设置。

GsonBuilder.setFieldNamingPolicy 方法与 Gson 提供的另一个枚举类 FieldNamingPolicy 配合使用，该枚举类提供了 5 种实现方式分别为：