Version: 1.5.x

数据转换

Forest支持JSON、XML、普通文本等数据转换形式。不需要接口调用者自己写具体的数据转换代码。

序列化

几乎所有数据格式的转换都包含序列化和反序列化,Forest的数据转换同样如此。

Forest中对数据进行序列化可以通过指定contentType属性或Content-Type头指定内容格式。

@Request(
url = "http://localhost:8080/hello/user",
type = "post",
contentType = "application/json" // 指定contentType为application/json
)
String postJson(@Body MyUser user); // 自动将user对象序列化为JSON格式

同理,指定为application/xml会将参数序列化为XML格式,text/plain则为文本,默认的application/x-www-form-urlencoded则为表格格式。

反序列化

HTTP请求响应后返回结果的数据同样需要转换,Forest则会将返回结果自动转换为您通过方法返回类型指定对象类型。这个过程就是反序列化,您可以通过dataType指定返回数据的反序列化格式。

@Request(
url = "http://localhost:8080/data",
dataType = "json" // 指定dataType为json,将按JSON格式反序列化数据
)
Map getData(); // 请求响应的结果将被转换为Map类型对象

转换器

在Forest中,序列化和反序列化过程都有Forest转换器来实现,其数据在Forest中的转换过程如图所示:

architecture

Forest提供了默认的转换器,其分成五大类:文本转换器、JSON转换器、XML转换器、二进制转换器、自动转换器。 各大类还可以继续细分为更具体的转换器,可以按类继承理解其分类。

转换器的继承体系请看如下树状结构:

ForestConverter接口
├── DefaultTextConverter类
├── ForestJsonConverter接口
| ├── ForestFastjsonConverter类
| ├── ForestJacksonConverter类
| └── ForestGsonConverter类
├── ForestXmlConverter接口
| └── ForestJaxbConverter类
├── DefaultBinaryConverter类
└── DefaultAutoConverter类

可以替换和使用的转换器类如下表:

转换器类类型描述
DefaultTextConvertertext默认文本数据转换器
ForestFastjsonConverterjson基于Fastjson框架的JSON转换器
ForestJacksonConverterjson基于Jackson框架的JSON转换器
ForestGsonConverterjson基于Gson框架的JSON转换器
ForestJaxbConverterxml基于Jaxb框架的XML转换器
DefaultBinaryConverterbinary默认二进制转换器,多在文件下载时使用
DefaultAutoConverterauto自动类型转换器,可以根据响应返回的数据自动嗅探数据类型并使用对应的转换器进行转换

更换转换器: SpringBoot项目

在Forest中已定义好默认的转换器,比如JSON的默认转为器为ForestFastjsonConverter,即FastJson的转换器。

在SpringBoot项目中,直接在 application.ymlapplication.properties 文件里配置便可。

forest:
# 转换器配置,支持 json, xml, text, binary 四种数据类型的配置
converters:
# JSON转换器
json:
# JSON转换器设置为GSON转换器
type: com.dtflys.forest.converter.json.ForestGsonConverter
# 同理,也可以设置成 Fastjson 或 Jackson 的转换器
# type: com.dtflys.forest.converter.json.ForestFastjsonConverter
# type: com.dtflys.forest.converter.json.ForestJacksonConverter
# 转换器的参数设置
parameters:
# JSON数据转换器的全局日期格式化配置
dateFormat: yyyy/MM/dd hh:mm:ss
# XML转换器
xml:
# 配置为JAXB转换器
type: com.dtflys.forest.converter.xml.ForestJaxbConverter
# 二进制转换器
binary:
# 配置为Forest默认二进制转换器
type: com.dtflys.forest.converter.binary.DefaultBinaryConverter
# 文本转换器
text:
# 配置为Forest默认文本转换器
type: com.dtflys.forest.converter.text.DefaultTextConverter

更换转换器: 非SpringBoot项目

在非SpringBoot项目修改转换器需要在Java代码中进行配置:

@Autowrired
private ForestConfiguration forestConfiguration;
... ...
// 更换JSON转换器为FastJson
forestConfiguration.setJsonConverter(new ForestFastjsonConverter());
// 更换JSON转换器为Jackson
forestConfiguration.setJsonConverter(new ForestJacksonConverter());
// 更换JSON转换器Gson
forestConfiguration.setJsonConverter(new ForestGsonConverter());
// 更换XML转换器JAXB
forestConfiguration.getConverterMap().put(ForestDataType.XML, new ForestJaxbConverter());

自定义转换器

在Forest中,每个转换类型都对应一个转换器对象,比如JSON格式的转换器有com.dtflys.forest.converter.json.ForestFastjsonConvertercom.dtflys.forest.converter.json.ForestGsonConvertercom.dtflys.forest.converter.json.ForestJacksonConverter三种,分别是基于FastJsonGsonJackson三种不同的JSON序列化框架。

当然,您也可以自定义自己的转换器,以适应自己项目的需要。只需三步便可完成自定义扩展转换器。

第一步. 定义一个转换器类,并实现com.dtflys.forest.converter.ForestConverter接口

/**
* 自定义一个Protobuf的转换器,并实现ForestConverter接口下的convertToJavaObject方法
*/
public class MyProtobufConverter implements ForestConverter {
public <T> T convertToJavaObject(String source, Class<T> targetType) {
// 将字符串参数source转换成目标Class对象
}
public <T> T convertToJavaObject(String source, Type targetType) {
// 将字符串参数source转换成目标Type(可能是一个泛型类型)对象
}
}

第二步. 注册您定义好的转换器类到ForestConfiguration

@Autowrired
private ForestConfiguration forestConfiguration;
...
// 设置文本转换器
forestConfiguration.getConverterMap().put(ForestDataType.TEXT, new MyProtobufConverter());
// 设置二进制转换器
forestConfiguration.getConverterMap().put(ForestDataType.BINARY, new MyProtobufConverter());
// 设置二进制转换器
forestConfiguration.getConverterMap().put(ForestDataType.BINARY, new MyProtobufConverter());

JSON转换器和XML转换器比较特殊,需要 implements 的类不是 ForestConverter

/**
* JSON转换器需要实现 ForestJsonConverter 接口
*/
public class MyJsonConverter implements ForestJsonConverter {
... ...
}
/**
* XML转换器需要实现 ForestXmlConverter 接口
*/
public class MyXmlConverter implements ForestXmlConverter {
... ...
}

注册到配置中

// 设置JSON转换器
forestConfiguration.setJsonConverter(new MyJsonConverter());
// 设置XML转换器
forestConfiguration.getConverterMap().put(ForestDataType.XML, new MyXmlConverter());
Last updated on