Spring中三大JSON框架的使用

发表于 2018年12月16日 | 分类于技术 |

在SpringBoot中,常常会需要把请求中的参数进行反序列化,得到我们需要的实体对象,在进行处理之后,再把实体序列化返回给请求方(这里不提什么DTO、VO、BO的概念,其实很多公司对这些领域模型的区分都不怎么严格,毕竟搬砖的靠技术,大佬们才谈规范和标准,在阿里巴巴的Java开发手册中对这些有比较详细的规约,建议参考)。大部分情况下,开放API的数据协议都是用的JSON(也就是请求的content-type:application/json,参数以json格式放在请求body中的,本文只讨论这种请求类型),常见的JSON序列化工具有Jackson(SpringBoot默认使用)、Gson、FastJson等等。下面看一下怎么使用它们。

一、Jackson

1.1 基本用法

Jackson是SpringBoot默认的JSON序列化/反序列化框架,对于content-type:application/json的请求参数,只需要在Controller的方法中使用@RequestBody注解到参数上,即可实现反序列化。下面是基本的示例代码,User.java(必须有getter、setter方法和默认的无参构造函数)、UserController.java(方法的参数必须有@RequestBody注解)。

// User.java
public class User2 {
 private Integer id;
 private String name;
 public Integer getId() {
 return id;
 }
 public void setId(Integer id) {
 this.id = id;
 }
 public String getName() {
 return name;
 }
 public void setName(String name) {
 this.name = name;
 }
}
// UserController.java
@RestController
public class UserController {
 private static final Logger LOGGER = LoggerFactory.getLogger(UserController.class);
 @RequestMapping(value = "/user/post", method = RequestMethod.POST)
 public ServiceResponse getUserByPost(@RequestBody User user) {
 LOGGER.info(user.getId() + ": " + user.getName());
 ServiceResponse serviceResponse = new ServiceResponse();
 serviceResponse.setCode(0);
 serviceResponse.setMessage("test");
 return serviceResponse;
 }
}
// ServiceResponse.java,作为getUserByPost的返回值,自动被序列化返回。
public class ServiceResponse {
 private int code;
 private String message;
 public int getCode() {
 return code;
 }
 public void setCode(int code) {
 this.code = code;
 }
 public String getMessage() {
 return message;
 }
 public void setMessage(String message) {
 this.message = message;
 }
}

用postman发出一个请求试试。

喜欢用curl的话,也可以用下面的命令发请求。

curl -X POST \
 http://127.0.0.1:8080/user/post \
 -H 'Content-Type: application/json' \
 -H 'cache-control: no-cache' \
 -d '{
	"id": 1,
	"name": "unclechen"
}'

返回结果如下,可以看到ServiceResponse对象,自动被框架序列化返回。

{
 "code": 0,
 "message": "test"
}

由此看到,作为SpringBoot中默认使用的JSON框架,基本上不用做任何事情,就可以实现json请求的参数反序列化以及处理结果的序列化。

注意:虽然不用做什么事情,但是也不能做多余的事。比如对于User.java类,一定要保证它会有一个无参数的构造函数。按照Java的规则,如果你没有指定任何构造函数,那么编译时会自动添加一个无参构造函数,但是如果你指定了含有参数的构造函数,那么就不会再添加一个无参构造函数了,此时反序列化就会失败,抛出com.fasterxml.jackson.databind.exc.InvalidDefinitionException。

1.2 字段命名映射的处理

实际业务上,有些API要求参数会以小写字母+下划线的方式命名,有些又要求以驼峰方式命名,有时可能又为了某种兼容,参数的名字可能和代码中实体的属性名称完全不同。我们在上面的User.java中增加一个private String personalPage属性(相应地也添加了setter/getter方法),看看如何解析这个参数。

然后构造一个新的请求,在这个请求中添加一个带有了小写字母加下划线的参数personal_page,我们发现反序列化之后的User对象的personalPage属性为null。这很好理解,框架没有这么智能,它并不会知道personalPage属性在序列化的数据中是叫personal_page的。为了指定序列化时这个属性的名称,我们可以给它使用@JsonProperty("personal_page")注解,这个注解也是Jackson这个框架提供的。

通过@JsonProperty注解可以指定序列化的属性名称,但是每一个属性如果都要这么写的话,就太费劲了,我们可以统一指定这种命名的解析规则。具体做法有两种,一种是配置的方式,一种是编程的方式。

application.properties配置文件中设置:spring.jackson.property-naming-strategy=CAMEL_CASE_TO_LOWER_CASE_WITH_UNDERSCORES(新版本好像已经用SNAKE_CASE替代了)。关于更多的配置参数,可以查看一下org.springframework.boot.autoconfigure.jackson.JacksonProperties这个类。配置文件里面有哪些Jackson的配置可以写,可以参考这里。
编程自定义ObjectMapper:ObjectMapper是Jackson的核心,它可以控制SpringBoot中如何使用Jackson的功能,下面通过配置的方式指定了自定义的ObjectMapper。这种方式除了可以配置参数名称的解析规则外,还可以指定更多的Jackson序列化和反序列化的规则。

具体使用ObjectMapper的时候有两种方式:一种是配置一个单例的ObjectMapper对象,如下所示。

// CustomObjectMapper.java
...
@Configuration
public class CustomObjectMapper {
 @Bean
 public ObjectMapper getObjectMapper() {
 ObjectMapper mapper = new ObjectMapper();
 // 指定PropertyNamingStrategy,甚至可以自定义PropertyNamingStrategy
 mapper.setPropertyNamingStrategy(PropertyNamingStrategy.SNAKE_CASE);
 return mapper;
 }
}

另一种方式是以在SpringBootApplication类中指定HttpMessageConverter来实现同样的功能。

@SpringBootApplication
public class DemoApplication extends WebMvcConfigurationSupport {
 public static void main(String[] args) {
 SpringApplication.run(DemoApplication.class, args);
 }
 @Override
 public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
 Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder();
 builder.propertyNamingStrategy(PropertyNamingStrategy.SNAKE_CASE);
 converters.add(new MappingJackson2HttpMessageConverter(builder.build()));
 }
}

1.3 时间类型的字段处理

配置文件的方式不赘述,spring.jackson.date-format=即可。

在1.2节提到了采用ObjectMapper可以设置参数解析的规则,时间类型的字段处理也是一种。具体方法是:

// CustomObjectMapper.java
mapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
// User.java
public class User {
 // 省略其他字段
 private LocalDate birthDay;
 public LocalDate getBirthDay() {
 return birthDay;
 }
 public void setBirthDay(LocalDate birthDay) {
 this.birthDay = birthDay;
 }
}

这样,在反序列化接收参数时候,都只能接收形如yyyy-MM-dd HH:mm:ss的字符串了。并且在序列化返回结果的时候也是返回这个格式。当然你也可以使用@JsonFormat(timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm:ss")注解。不过有时为了让接口可以更灵活,可能我们的VO/DTO里面还是会把XXXTime定义成String,等到反序列化完成之后,再手动校验它们。

1.4 枚举类型的字段处理

这个更简单,啥也不用干,定义一个枚举Gender,Jackson框架自动会帮你反序列化解析成对象的属性。

// Gender.java
public enum Gender {
 MALE, FEMALE
}
// User.java
public class User2 {
 // 省略其他字段
 private Gender gender;
 // 省略getter/setter
}

当传入的参数不在枚举值范围的时候,框架会抛出异常,我们可以在全局的异常Handler里面处理它,然后向用户返回友好的信息。

如果不希望Jackson框架抛出异常的话,可以对自定义的ObjectMapper进行设置,ObjectMapper.configure(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_AS_NULL, true);。

1.5 Jackson序列化小结

总结下来,就是两种方式,一种靠注解,一种靠CustomObjectMapper,注解适合灵活用在某个属性上(灵活的意思是比如,某个属性名称完全没有任何规则,参数叫a,而属性叫b),如果整个工程都是统一的风格,那么最好用CustomObjectMapper来节省体力(个人也更推荐这种做法,节省体力,API风格规范统一,便于团队协作)。

两种方式在能力上其实都是对应的,最灵活的方式就是可以自己定义serializer和deserializer,具体如何实现,可以参考文档。不过其实Jackson已经提供了足够多的反序列化配置选项来给我们用,在DeserializationFeature.java里面我们可以找到诸如READ_UNKNOWN_ENUM_VALUES_AS_NULL这样的配置。

反序列化还可以和前一篇提到的参数校验结合起来进行使用,此时只需要将@RequetsBody注解前面加上一个@Validated注解即可。

二、Gson

除了默认的Jackson,还可以使用Gson来对参数进行反序列化,具体实现是通过GsonHttpMessageConverter。我们先看一下Spring里面的HttpMessageConverter继承关系,如下图所示。

了解这个之后,看一下如何将SpringBoot的Json框架替换成Gson。

2.1 基本用法

第一步,引入Gson库。

dependencies {
 implementation('org.springframework.boot:spring-boot-starter-web')
 implementation('com.google.code.gson:gson:2.8.4')
}
configurations {
 compile.exclude group: 'com.fasterxml.jackson.core'
}

这里强制剔除掉Jackson是为了防止SpringBoot的AutoConfig机制因为Jackson的类存在导致Gson的失效。Spring-AutoConfig使用的是@ConditionalOnClass(Gson.class)自动配置Gson,使用的是@ConditionalOnClass(ObjectMapper.class)自动配置的Jackson,由于ObjectMapper.class在com.fasterxml.jackson.core中,所以把它所在的库exclude掉。

第二步,回到SpringBootApplication类中,添加GsonHttpMessageConverter到Coverters。同时去掉Jackson的Converter和ObjectMapper(如果有的话)。

@SpringBootApplication
public class DemoApplication extends WebMvcConfigurationSupport {
 public static void main(String[] args) {
 SpringApplication.run(DemoApplication.class, args);
 }
 @Override
 public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
 // Gson
 GsonHttpMessageConverter gsonHttpMessageConverter = new GsonHttpMessageConverter();
 converters.add(gsonHttpMessageConverter);
 }
}

除了代码方式,还可以写到配置文件。具体可以配置的属性有哪些,可以参考源代码com.google.gson.FieldNamingPolicy.java。

1
2
3

// application.properties
# Naming policy that should be applied to an object's field during serialization and deserialization.
spring.gson.field-naming-policy=LOWER_CASE_WITH_UNDERSCORES

配置这里,我始终都没有实践成功,虽然我确定已经排除掉了Jackson库,但是spring.gson.field-naming-policy= LOWER_CASE_WITH_UNDERSCORES不知道为什么一直都没有配置成功。希望熟悉的朋友可以指点一下。

2.2 字段命名映射的处理

上面只是很简单的添加了Gson作为Json框架,使用GsonBuilder创建Gson对象,可以对序列化的映射规则进行配置,代码如下:

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
 // Gson
 GsonHttpMessageConverter gsonHttpMessageConverter = new GsonHttpMessageConverter();
 // 自定义Gson,配置参数解析规则
 gsonHttpMessageConverter.setGson(new GsonBuilder()
 .setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES)
 .create());
 converters.add(gsonHttpMessageConverter);
}

除了这种方式,还可以在SpringBoot的配置文件中配置Gson的Mapper规则。

1
2
3

// application.properties
# Preferred JSON mapper to use for HTTP message conversion.
spring.http.converters.preferred-json-mapper=gson

2.3 时间参数的处理

既然都是用GsonBuilder,那么很简单加一行.setDateFormat("yyyy-MM-dd HH:mm:ss")即可。

2.4 枚举参数的处理

和Jackson一样,Gson也不需要我们干什么就会自动将字符串形式的参数转换成枚举对象。

三、FastJson

3.1 基本用法

阿里出产的轮子,官方有wiki-《在 Spring 中集成 Fastjson》,这里我就不搬运了。本质上也是一样的,替换SpringBoot自带的HttpMessageConverter为FastJsonHttpMessageConverter即可。

在官方文档中提到一句:

SpringBoot 2.0.1版本中加载WebMvcConfigurer的顺序发生了变动,故需使用converters.add(0, converter);指定FastJsonHttpMessageConverter在converters内的顺序,否则在SpringBoot 2.0.1及之后的版本中将优先使用Jackson处理。详情:WebMvcConfigurer is overridden by WebMvcAutoConfiguration #12389

3.2 配置映射规则

@SpringBootApplication
public class DemoApplication extends WebMvcConfigurationSupport {
 public static void main(String[] args) {
 SpringApplication.run(DemoApplication.class, args);
 }
 @Override
 public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
 FastJsonHttpMessageConverter converter = new FastJsonHttpMessageConverter();
 //自定义配置...
 FastJsonConfig config = new FastJsonConfig(); // 按照阿里的文档说,生产环境要尽可能单例配置对象
 config.setDateFormat("yyyy-MM-dd HH:mm:ss"); // 设置时间格式
 // 字段名称映射规则,详见:https://github.com/alibaba/fastjson/wiki/PropertyNamingStrategy_cn
 config.getParserConfig().propertyNamingStrategy = PropertyNamingStrategy.SnakeCase; // 设置反序列化名称规则
 config.getSerializeConfig().propertyNamingStrategy = PropertyNamingStrategy.SnakeCase; // 设置序列化名称规则
 converter.setFastJsonConfig(config);
 // 添加下面这一段是因为高版本的Fastjson的MediaType默认为*/*,而高版本的Spring不允许这样,需要明确指定MediaType。详见:https://github.com/alibaba/fastjson/issues/1554
 List<MediaType> supportedMediaTypes = new ArrayList<>();
 supportedMediaTypes.add(MediaType.APPLICATION_JSON);
 supportedMediaTypes.add(MediaType.APPLICATION_JSON_UTF8);
 supportedMediaTypes.add(MediaType.APPLICATION_ATOM_XML);
 supportedMediaTypes.add(MediaType.APPLICATION_FORM_URLENCODED);
 supportedMediaTypes.add(MediaType.APPLICATION_OCTET_STREAM);
 supportedMediaTypes.add(MediaType.APPLICATION_PDF);
 supportedMediaTypes.add(MediaType.APPLICATION_RSS_XML);
 supportedMediaTypes.add(MediaType.APPLICATION_XHTML_XML);
 supportedMediaTypes.add(MediaType.APPLICATION_XML);
 supportedMediaTypes.add(MediaType.IMAGE_GIF);
 supportedMediaTypes.add(MediaType.IMAGE_JPEG);
 supportedMediaTypes.add(MediaType.IMAGE_PNG);
 supportedMediaTypes.add(MediaType.TEXT_EVENT_STREAM);
 supportedMediaTypes.add(MediaType.TEXT_HTML);
 supportedMediaTypes.add(MediaType.TEXT_MARKDOWN);
 supportedMediaTypes.add(MediaType.TEXT_PLAIN);
 supportedMediaTypes.add(MediaType.TEXT_XML);
 converter.setSupportedMediaTypes(supportedMediaTypes);
 converters.add(0, converter); // 加入到HttpMessageConverterList的最前面
 }
}

四、性能

这里我也没有做过真正的测试,网上随便一搜可以找到大量讨论,我个人的态度比较开放,觉得在功能、性能上,三个框架都能满足基本使用,喜欢使用最简洁的方式。不过比较早的时候我开发Android App用的都是Gson,猜测可能是Gson这个库比较精简,没有太多复杂的功能,不过后来fastjson也针对Android出了专门的版本。到现在,Kotlin出来了,大家可能又有适配Kotlin的需求,具体还是看各自的需要来选择吧。

五、总结

三大框架各自有自己的默认配置(实际上默认配置可能是随着框架的版本而变化的),使用框架的时候要熟悉它们,才可以避免一些麻烦。

比如Jackson,默认情况下,对请求中多余的属性,会反序列化失败,需要把DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES设置为false才可以反序列化请求参数。
比如Gson,默认会忽略多余的属性。但是对java8里面的LocalDate类型的属性,反序列化需要手动编写deserialize方法,因为Gson默认只能处理java.util.Date类型的属性。

最后对于怎么使用框架,如果写配置能满足,那是最简单的、最方便管理的。common-application-properties里面预制了大量的配置,但是有时配置可能不够,这时还是编程方式来的更好一些。总之,我建议统一使用一种方式,保证整个项目风格的统一最好。

本文作者:unclechen
本文链接: 2018/12/16/Spring中三大JSON框架的使用/
版权声明: 本文采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。转载请注明出处!