Android Gson 从Java对象到JsonWriter的转换链路原理剖析
一、转换链路核心流程概述
1.1 序列化的本质与目标
从Java对象到JsonWriter的转换是Gson序列化(Serialization)的核心过程,其本质是将具有复杂对象图结构的Java对象,按照JSON格式规范,通过流式写入器(JsonWriter)输出为字符流。目标是实现Java对象状态的持久化表示,便于数据存储、网络传输或跨平台交互。
1.2 关键组件与调用链
整个转换链涉及以下核心组件:
- Gson:序列化入口,协调各组件工作。
- TypeAdapter:具体类型的序列化器,负责对象与JSON的直接转换。
- JsonWriter:底层JSON字符流写入器,提供流式API。
- TypeAdapterFactory:工厂链,用于创建TypeAdapter实例。
- Reflection序列化机制:通过反射处理普通Java对象的字段。
1.3 主调用流程
graph LR
A[Java对象] --> B{获取TypeAdapter}
B -->|自定义适配器| C[UserTypeAdapter.write]
B -->|内置适配器| D[ReflectiveTypeAdapter.write]
C --> E[调用JsonWriter API]
D --> E
E --> F[JsonWriter写入字符流]
二、Gson序列化入口与TypeAdapter解析
2.1 Gson.toJson()的重载体系
Gson提供了多个toJson()方法,最终都会调用核心实现:
public class Gson {
public String toJson(Object src) {
// 处理null值
if (src == null) {
return toJson(Null.class, Null.class);
}
// 反射获取对象类型
Type type = src.getClass();
return toJson(src, type);
}
public String toJson(Object src, Type typeOfSrc) {
// 创建StringWriter
StringWriter writer = new StringWriter();
// 核心序列化逻辑
toJson(src, typeOfSrc, writer);
return writer.toString();
}
public void toJson(Object src, Type typeOfSrc, Appendable writer) throws JsonIOException {
// 创建JsonWriter实例
JsonWriter jsonWriter = newJsonWriter(Streams.writerForAppendable(writer));
try {
// 执行序列化
toJson(src, typeOfSrc, jsonWriter);
} finally {
// 关闭JsonWriter
try {
jsonWriter.close();
} catch (IOException e) {
throw new JsonIOException(e);
}
}
}
private void toJson(Object src, Type typeOfSrc, JsonWriter writer) throws JsonIOException {
// 处理null值
if (src == null) {
TypeAdapter<Object> adapter = getAdapter(TypeToken.get(Object.class));
adapter.write(writer, null);
return;
}
// 获取TypeAdapter
TypeAdapter<?> adapter = getAdapter(TypeToken.get(typeOfSrc));
try {
// 调用适配器的write方法
adapter.write(writer, src);
} catch (IOException e) {
throw new JsonIOException(e);
}
}
}
2.2 TypeAdapter的获取逻辑
Gson通过getAdapter()方法从工厂链中查找对应的TypeAdapter:
public <T> TypeAdapter<T> getAdapter(TypeToken<T> type) {
// 从缓存获取
TypeAdapter<?> cached = typeTokenCache.get(type);
if (cached != null) {
return (TypeAdapter<T>) cached;
}
synchronized (typeTokenCache) {
cached = typeTokenCache.get(type);
if (cached != null) {
return (TypeAdapter<T>) cached;
}
// 遍历工厂链创建适配器
TypeAdapter<T> adapter = null;
for (TypeAdapterFactory factory : factories) {
adapter = factory.create(this, type);
if (adapter != null) {
break;
}
}
if (adapter == null) {
throw new IllegalArgumentException("Gson cannot serialize " + type);
}
// 缓存适配器
typeTokenCache.put(type, adapter);
return adapter;
}
}
三、TypeAdapterFactory工厂链解析
3.1 工厂链的优先级顺序
Gson的工厂链按照注册顺序执行,内置工厂包括:
- 用户自定义工厂:通过
GsonBuilder.registerTypeAdapterFactory()添加,优先级最高。 - JsonSerializer/Deserializer工厂:处理
@JsonAdapter注解。 - 反射工厂(ReflectiveTypeAdapterFactory):处理普通Java对象。
- 基本类型工厂:如
PrimitiveTypeAdapterFactory。
3.2 反射工厂的核心逻辑
ReflectiveTypeAdapterFactory用于处理无自定义适配器的普通对象:
final class ReflectiveTypeAdapterFactory implements TypeAdapterFactory {
private final ConstructorConstructor constructorConstructor;
private final FieldNamingStrategy fieldNamingPolicy;
@Override
public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> type) {
Class<? super T> raw = type.getRawType();
// 跳过接口和抽象类
if (!Object.class.isAssignableFrom(raw)) {
return null;
}
// 创建反射适配器
return new Adapter<>(
constructorConstructor.get(type), // 对象构造器
getBoundFields(gson, type, raw) // 绑定字段集合
);
}
private Map<String, BoundField> getBoundFields(Gson gson, TypeToken<?> type, Class<?> raw) {
Map<String, BoundField> fields = new LinkedHashMap<>();
// 遍历类层次结构(包括父类)
while (raw != Object.class) {
// 获取当前类所有字段
Field[] declaredFields = raw.getDeclaredFields();
for (Field field : declaredFields) {
// 检查字段是否可序列化/反序列化
boolean serialize = !excludeField(field, true);
boolean deserialize = !excludeField(field, false);
if (!serialize && !deserialize) {
continue;
}
field.setAccessible(true);
// 获取字段的JSON名称(支持@SerializedName注解)
List<String> fieldNames = getFieldNames(field);
// 创建BoundField实例
BoundField boundField = createBoundField(
gson, field, fieldNames,
TypeToken.get($Gson$Types.resolve(type.getType(), raw, field.getGenericType())),
serialize, deserialize
);
// 处理字段名冲突
for (String name : fieldNames) {
if (fields.put(name, boundField) != null) {
throw new IllegalArgumentException("Duplicate field name: " + name);
}
}
}
// 处理父类
type = TypeToken.get($Gson$Types.resolve(type.getType(), raw, raw.getGenericSuperclass()));
raw = type.getRawType();
}
return fields;
}
}
四、ReflectiveTypeAdapter的序列化逻辑
4.1 Adapter类的write方法
反射适配器的核心序列化逻辑在Adapter.write()中:
public static final class Adapter<T> extends TypeAdapter<T> {
private final ObjectConstructor<T> constructor;
private final Map<String, BoundField> boundFields;
@Override
public void write(JsonWriter out, T value) throws IOException {
if (value == null) {
out.nullValue();
return;
}
// 标记对象已序列化,防止循环引用
out.beginObject();
// 遍历所有绑定字段
for (BoundField field : boundFields.values()) {
if (field.serialized) {
// 写入字段名
out.name(field.name);
// 写入字段值
field.write(out, value);
}
}
out.endObject();
}
}
4.2 BoundField的write实现
BoundField是字段序列化的具体执行者,根据字段类型选择不同逻辑:
abstract static class BoundField {
final String name;
final boolean serialized;
final boolean deserialized;
protected BoundField(String name, boolean serialized, boolean deserialized) {
this.name = name;
this.serialized = serialized;
this.deserialized = deserialized;
}
abstract void write(JsonWriter writer, Object value) throws IOException, IllegalAccessException;
// 基本类型字段的序列化实现
static final class PrimitiveField<T> extends BoundField {
private final TypeAdapter<T> typeAdapter;
private final Field field;
PrimitiveField(String name, boolean serialized, boolean deserialized,
TypeAdapter<T> typeAdapter, Field field) {
super(name, serialized, deserialized);
this.typeAdapter = typeAdapter;
this.field = field;
}
@Override
void write(JsonWriter writer, Object value) throws IOException, IllegalAccessException {
T fieldValue = (T) field.get(value);
// 处理null值(根据Gson配置决定是否写入)
if (fieldValue == null && !gson.serializeNulls()) {
return;
}
// 调用TypeAdapter写入值
typeAdapter.write(writer, fieldValue);
}
}
// 引用类型字段的序列化实现
static final class ReferenceField<T> extends BoundField {
private final TypeAdapter<T> typeAdapter;
private final Field field;
ReferenceField(String name, boolean serialized, boolean deserialized,
TypeAdapter<T> typeAdapter, Field field) {
super(name, serialized, deserialized);
this.typeAdapter = typeAdapter;
this.field = field;
}
@Override
void write(JsonWriter writer, Object value) throws IOException, IllegalAccessException {
T fieldValue = (T) field.get(value);
if (fieldValue == null) {
writer.nullValue();
return;
}
// 递归调用子对象的序列化
typeAdapter.write(writer, fieldValue);
}
}
}
五、JsonWriter的底层实现
5.1 JsonWriter的状态管理
JsonWriter维护一个状态栈,用于跟踪当前写入的JSON结构层次:
public final class JsonWriter implements Closeable, Flushable {
// 当前写入状态
private int[] stack = new int[32];
private int stackSize = 0;
{
stack[stackSize++] = BEGIN_DOCUMENT;
}
// 写入JSON对象开始标记
public JsonWriter beginObject() throws IOException {
// 检查状态合法性
beforeValue(true);
// 压入对象状态
push(EMPTY_OBJECT);
out.write('{');
return this;
}
// 写入JSON数组开始标记
public JsonWriter beginArray() throws IOException {
// 检查状态合法性
beforeValue(false);
// 压入数组状态
push(EMPTY_ARRAY);
out.write('[');
return this;
}
// 写入字段名
public JsonWriter name(String name) throws IOException {
if (name == null) throw new NullPointerException("name == null");
// 检查状态合法性
beforeName();
// 写入引号和转义后的字段名
string(name);
out.write(':');
// 更新状态
stack[stackSize - 1] = NONEMPTY_OBJECT;
return this;
}
// 写入字符串值
public JsonWriter value(String value) throws IOException {
if (value == null) {
return nullValue();
}
// 检查状态合法性
beforeValue(false);
// 写入引号和转义后的字符串
string(value);
return this;
}
// 写入原始值(不进行转义)
public JsonWriter jsonValue(String value) throws IOException {
if (value == null) {
return nullValue();
}
// 检查状态合法性
beforeValue(false);
out.append(value);
return this;
}
// 写入null值
public JsonWriter nullValue() throws IOException {
beforeValue(false);
out.write("null");
return this;
}
// 写入布尔值
public JsonWriter value(boolean value) throws IOException {
beforeValue(false);
out.write(value ? "true" : "false");
return this;
}
// 写入整数值
public JsonWriter value(long value) throws IOException {
beforeValue(false);
out.write(Long.toString(value));
return this;
}
// 写入浮点数值
public JsonWriter value(double value) throws IOException {
// 检查NaN和Infinity
if (!Double.isFinite(value)) {
throw new IllegalArgumentException("Numeric values must be finite, but was " + value);
}
beforeValue(false);
out.write(Double.toString(value));
return this;
}
// 写入JSON对象结束标记
public JsonWriter endObject() throws IOException {
// 检查状态合法性
if (stackSize == 0) {
throw new IllegalStateException("JsonWriter is closed.");
}
int context = peek();
if (context != NONEMPTY_OBJECT && context != EMPTY_OBJECT) {
throw new IllegalStateException("Nesting problem.");
}
// 弹出当前状态
stackSize--;
if (context == NONEMPTY_OBJECT) {
out.write('\n');
}
out.write('}');
// 更新父状态
afterValue();
return this;
}
// 写入JSON数组结束标记
public JsonWriter endArray() throws IOException {
// 检查状态合法性
if (stackSize == 0) {
throw new IllegalStateException("JsonWriter is closed.");
}
int context = peek();
if (context != NONEMPTY_ARRAY && context != EMPTY_ARRAY) {
throw new IllegalStateException("Nesting problem.");
}
// 弹出当前状态
stackSize--;
if (context == NONEMPTY_ARRAY) {
out.write('\n');
}
out.write(']');
// 更新父状态
afterValue();
return this;
}
// 转义并写入字符串
private void string(String value) throws IOException {
out.write('"');
// 遍历字符串进行转义处理
for (int i = 0, length = value.length(); i < length; i++) {
char c = value.charAt(i);
switch (c) {
case '"':
out.write("\\\"");
break;
case '\\':
out.write("\\\\");
break;
case '\b':
out.write("\\b");
break;
case '\f':
out.write("\\f");
break;
case '\n':
out.write("\\n");
break;
case '\r':
out.write("\\r");
break;
case '\t':
out.write("\\t");
break;
default:
// 处理需要Unicode转义的字符
if (c <= 0x1F || (c >= 0x7F && c <= 0x9F) || (c >= 0xF000)) {
out.write("\\u");
out.write(toHexChar((c >> 12) & 0xF));
out.write(toHexChar((c >> 8) & 0xF));
out.write(toHexChar((c >> 4) & 0xF));
out.write(toHexChar(c & 0xF));
} else {
out.write(c);
}
break;
}
}
out.write('"');
}
}
5.2 字符流输出优化
JsonWriter通过多种方式优化字符流输出:
- 缓冲输出:内部使用BufferedWriter减少IO次数
- 状态预检查:在写入前检查状态,避免生成非法JSON
- 高效转义:采用查表和位运算快速处理特殊字符
- 批量写入:使用write(char[])批量写入字符数组
5.3 缩进与格式化控制
JsonWriter支持缩进格式化,通过setIndent()方法控制:
public JsonWriter setIndent(String indent) {
if (indent.length() == 0) {
this.indent = null;
this.newline = null;
} else {
this.indent = indent;
this.newline = "\n";
}
return this;
}
在写入对象和数组时会根据缩进配置添加换行和缩进:
private void beforeName() throws IOException {
int context = peek();
if (context == EMPTY_OBJECT) {
// 空对象,更新状态
stack[stackSize - 1] = NONEMPTY_OBJECT;
if (newline != null) {
out.write(newline);
indent(out, stackSize);
}
} else if (context == NONEMPTY_OBJECT) {
// 非空对象,添加逗号分隔
out.write(',');
if (newline != null) {
out.write(newline);
indent(out, stackSize);
}
} else {
throw new IllegalStateException("Nesting problem.");
}
}
private void indent(Writer out, int stackSize) throws IOException {
// 根据当前栈深度添加缩进
for (int i = 1; i < stackSize; i++) {
out.write(indent);
}
}
六、集合与数组的序列化
6.1 集合类型的处理
Gson对集合类型(如List、Set)的序列化由CollectionTypeAdapterFactory处理:
public final class CollectionTypeAdapterFactory implements TypeAdapterFactory {
private final ConstructorConstructor constructorConstructor;
@Override
public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> typeToken) {
Type type = typeToken.getType();
Class<? super T> rawType = typeToken.getRawType();
// 检查是否为集合类型
if (!Collection.class.isAssignableFrom(rawType)) {
return null;
}
// 解析集合元素类型
Type elementType = $Gson$Types.getCollectionElementType(type, rawType);
TypeAdapter<?> elementTypeAdapter = gson.getAdapter(TypeToken.get(elementType));
// 创建集合构造器
ObjectConstructor<T> constructor = constructorConstructor.get(typeToken);
//noinspection unchecked
TypeAdapter<T> result = new Adapter(gson, elementType, elementTypeAdapter, constructor);
return result;
}
private static final class Adapter<E> extends TypeAdapter<Collection<E>> {
private final TypeAdapter<E> elementTypeAdapter;
private final ObjectConstructor<? extends Collection<E>> constructor;
Adapter(Gson context, Type elementType,
TypeAdapter<E> elementTypeAdapter,
ObjectConstructor<? extends Collection<E>> constructor) {
this.elementTypeAdapter = new TypeAdapterRuntimeTypeWrapper<>(context, elementTypeAdapter, elementType);
this.constructor = constructor;
}
@Override
public Collection<E> read(JsonReader in) throws IOException {
// 集合反序列化逻辑
if (in.peek() == JsonToken.NULL) {
in.nextNull();
return null;
}
Collection<E> collection = constructor.construct();
in.beginArray();
while (in.hasNext()) {
E instance = elementTypeAdapter.read(in);
collection.add(instance);
}
in.endArray();
return collection;
}
@Override
public void write(JsonWriter out, Collection<E> collection) throws IOException {
if (collection == null) {
out.nullValue();
return;
}
// 开始写入数组
out.beginArray();
for (E element : collection) {
// 递归序列化每个元素
elementTypeAdapter.write(out, element);
}
out.endArray();
}
}
}
6.2 数组类型的处理
数组序列化由ArrayTypeAdapter处理,它会根据数组元素类型选择合适的适配器:
public final class ArrayTypeAdapter<T> extends TypeAdapter<T[]> {
public static final Factory FACTORY = new Factory() {
@Override
public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> typeToken) {
Type type = typeToken.getType();
if (!(type instanceof Class<?>)) {
return null;
}
Class<?> rawType = typeToken.getRawType();
if (!rawType.isArray()) {
return null;
}
// 获取数组元素类型
Type componentType = $Gson$Types.getArrayComponentType(type);
TypeAdapter<?> componentTypeAdapter = gson.getAdapter(TypeToken.get(componentType));
// 创建数组类型适配器
Class<?> componentRawType = $Gson$Types.getRawType(componentType);
TypeAdapter<T[]> result = new ArrayTypeAdapter<>(
gson, componentTypeAdapter, componentRawType);
return result;
}
};
private final Class<T> componentType;
private final TypeAdapter<T> componentTypeAdapter;
public ArrayTypeAdapter(Gson context, TypeAdapter<T> componentTypeAdapter, Class<T> componentType) {
this.componentTypeAdapter = new TypeAdapterRuntimeTypeWrapper<>(context, componentTypeAdapter, componentType);
this.componentType = componentType;
}
@Override
public T[] read(JsonReader in) throws IOException {
// 数组反序列化逻辑
if (in.peek() == JsonToken.NULL) {
in.nextNull();
return null;
}
// 读取数组元素
List<T> list = new ArrayList<>();
in.beginArray();
while (in.hasNext()) {
T instance = componentTypeAdapter.read(in);
list.add(instance);
}
in.endArray();
// 转换为数组
int size = list.size();
@SuppressWarnings("unchecked")
T[] array = (T[]) Array.newInstance(componentType, size);
return list.toArray(array);
}
@Override
public void write(JsonWriter out, T[] array) throws IOException {
if (array == null) {
out.nullValue();
return;
}
// 开始写入数组
out.beginArray();
for (T element : array) {
// 递归序列化每个元素
componentTypeAdapter.write(out, element);
}
out.endArray();
}
}
七、自定义序列化与@JsonAdapter注解
7.1 自定义TypeAdapter实现
开发者可以通过继承TypeAdapter实现自定义序列化逻辑:
public class DateTypeAdapter extends TypeAdapter<Date> {
private final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
@Override
public void write(JsonWriter out, Date value) throws IOException {
if (value == null) {
out.nullValue();
return;
}
// 自定义日期格式
String dateString = dateFormat.format(value);
out.value(dateString);
}
@Override
public Date read(JsonReader in) throws IOException {
if (in.peek() == JsonToken.NULL) {
in.nextNull();
return null;
}
// 解析自定义日期格式
String dateString = in.nextString();
try {
return dateFormat.parse(dateString);
} catch (ParseException e) {
throw new JsonSyntaxException(e);
}
}
}
7.2 使用@JsonAdapter注解
通过@JsonAdapter注解可以将自定义适配器应用到类上:
@JsonAdapter(DateTypeAdapter.class)
public class MyModel {
private Date createTime;
// 其他字段和方法
}
7.3 JsonAdapter注解的处理
Gson通过JsonAdapterAnnotationTypeAdapterFactory处理注解:
final class JsonAdapterAnnotationTypeAdapterFactory implements TypeAdapterFactory {
private final ConstructorConstructor constructorConstructor;
@Override
public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> targetType) {
// 检查类上是否有@JsonAdapter注解
JsonAdapter annotation = targetType.getRawType().getAnnotation(JsonAdapter.class);
if (annotation == null) {
return null;
}
// 创建自定义适配器实例
return createTypeAdapter(constructorConstructor, gson, targetType, annotation);
}
@SuppressWarnings({"unchecked", "rawtypes"})
private TypeAdapter<?> createTypeAdapter(
ConstructorConstructor constructorConstructor, Gson gson,
TypeToken<?> type, JsonAdapter annotation) {
// 获取适配器类
Class<?> adapterClass = annotation.value();
// 处理TypeAdapter子类
if (TypeAdapter.class.isAssignableFrom(adapterClass)) {
Class<TypeAdapter<?>> typeAdapterClass = (Class<TypeAdapter<?>>) adapterClass;
ObjectConstructor<TypeAdapter<?>> constructor = constructorConstructor.get(TypeToken.get(typeAdapterClass));
TypeAdapter<?> typeAdapter = constructor.construct();
return typeAdapter.nullSafe();
}
// 处理JsonSerializer/Deserializer实现类
if (JsonSerializer.class.isAssignableFrom(adapterClass) ||
JsonDeserializer.class.isAssignableFrom(adapterClass)) {
// 创建JsonSerializer/Deserializer实例
Object instance = constructorConstructor.get(TypeToken.get(adapterClass)).construct();
JsonSerializer<?> serializer = null;
JsonDeserializer<?> deserializer = null;
if (instance instanceof JsonSerializer) {
serializer = (JsonSerializer<?>) instance;
}
if (instance instanceof JsonDeserializer) {
deserializer = (JsonDeserializer<?>) instance;
}
// 创建适配器包装器
return new TreeTypeAdapter<>(serializer, deserializer, gson, type, null);
}
throw new IllegalArgumentException(
"@JsonAdapter value must be TypeAdapter, TypeAdapterFactory, "
+ "JsonSerializer or JsonDeserializer reference.");
}
}
八、性能优化与内存管理
8.1 序列化性能关键因素
Gson序列化性能受以下因素影响:
- 反射开销:通过反射访问字段和方法
- 类型适配器链:查找适配器的过程
- 字符串处理:JSON字符串的构建和转义
- 对象图深度:递归处理嵌套对象
8.2 性能优化策略
- 使用自定义TypeAdapter:避免反射,直接操作对象
- 缓存Gson实例:减少工厂链初始化开销
- 批量序列化:避免频繁创建JsonWriter
- 禁用不必要的功能:如缩进、序列化null值
8.3 内存优化
Gson在序列化过程中的内存优化:
- 对象池技术:复用临时对象减少GC压力
- 字符缓冲区优化:调整缓冲区大小减少内存拷贝
- 延迟序列化:对大型对象采用流式处理
- 弱引用缓存:对不常用的适配器使用弱引用缓存
九、总结与展望
9.1 转换链路的核心机制
Gson从Java对象到JsonWriter的转换链路是一个精心设计的组件协作系统,核心机制包括:
- 适配器模式:通过TypeAdapter实现不同类型的序列化策略
- 工厂链:灵活的工厂链设计支持扩展和自定义
- 反射机制:通过反射动态访问对象字段
- 状态管理:JsonWriter的状态栈确保生成合法JSON
9.2 未来发展方向
- Kotlin协程支持:在异步场景下提供更高效的序列化方式
- 字节码生成:通过字节码生成技术减少反射开销
- 多平台优化:针对不同平台(如Android、JVM)提供定制优化
- 与现代框架集成:更好地支持Kotlin、Flow、Coroutines等新特性
- 内存效率提升:进一步优化内存使用,减少临时对象分配
通过不断演进,Gson将继续为开发者提供高效、灵活、易用的JSON处理解决方案,同时适应不断变化的Android开发生态。