Spring Boot教程(12) – 编写JSON API

目前很多公司开发项目,都选择了前后端分离的方式,不仅仅因为前端现在有丰富的生态和活跃的社区,更是因为分离让前端和后端的耦合度大大降低。前后端开发人员各司其职,各自做擅长的事情,提高了团队效率。而现在在电脑前学Spring Boot的你,很可能在将来的工作中扮演后端API开发的角色。

前端和后端的数据交换格式,现在用的最广泛的是JSON,Spring Boot的Web Starter也自带了JSON的支持,而且选用了Jackson库,我之前也写过它如何使用,阅读本文之前最好看一看。另外,还有个JSON库叫Gson,使用也比较广泛,加入了Gson的依赖之后,可以通过配置将其作为默认的JSON库。

对于前后端一体的应用,请求处理处理方法会返回模板的名字用来生成页面。而写接口的话,就需要在方法上添加@ResponseBody注解。你返回一个字符串,请求接口就会得到一个字符串。

如果你的控制器里的所有方法都是API,那么可以将@Controller替换成@RestController,这样不用在每个方法上都添加@ResponseBody了。

接下来看看如何返回JSON(不要告诉我你是通过手动拼接字符串来完成的)。Spring Boot的自动配置会给你自动生成一个ObjectMapper对象,你可以通过自动配置引入它。同时它可以用来创建ObjectNode,方便操作JSON,我们看个例子:

图中我们创建了一个ObjectNode对象,加点数据,并将其直接返回。通过请求这个API,就得到了JSON对象。你一定想问,我返回了个对象,Spring怎么就知道该怎么转换呢?

这样的转换工作是通过HttpMessageConverter来完成的,程序运行的时候,会有个HttpMessageConverter列表,得到方法返回的对象之后,框架会逐个询问谁能完成转换。对于Spring Boot来说,自动配置会给你生成很多HttpMessageConverter对象的。相关逻辑在源码HttpMessageConvertersAutoConfiguration中,如果你引入了Jackson,那么会得到一个MappingJackson2HttpMessageConverter,把ObjectNode转化为响应中的JSON字符串的工作就是他做的。HttpMessageConvertersAutoConfiguration里还配置了个StringHttpMessageConverter,如果请求处理方法返回的是字符串,会交由它来处理,本文的第一个例子就是这种情况。HttpMessageConverter相关的东西还是挺多的,我就不展开讲了。

直接返回ObjectNode的做法还不是很直观。现在通行的做法是把JSON映射成Java对象,这样理解起来更清晰,重构起来更容易。

默认情况下,你的请求结果的状态码是200,代表请求成功。如果你的请求需要返回不同的状态码,可以在方法上添加@ResponseStatus注解:

如果你的业务逻辑比较复杂,同一个请求可能返回各种各样的状态码。那就需要在代码中控制返回不同的状态码,可以将方法的返回值改成ResponseEntity类型的。

如果这种还是不能满足你的需要,比如你的返回值是不只是Player对象,可能是其他的JSON对象,那么你把返回值写成ResponseEntity,不声明具体的body类型。这样请求的返回结果就可以随意定制了,随意修改body,随意修改header,随意修改状态码。

我建议吧,你的请求处理方法,最好只返回单一的对象。这样的话,逻辑更清晰一点,别人看见你的代码就知道这个接口会返回什么样的东西,理解代码的时候有针对性。如果方法执行的过程中抛出了异常,就让@ExceptionHandler来处理不同的异常,根据异常类型来确定状态码,header和body等。

框架提供了编写API的能力,至于你的API风格如何设计,规范如何,还得自己定。现在网上教程一般都介绍RESTful风格,他用URL来定位资源,用HTTP方法来定义操作,以后我们有机会再分享下怎样更好地编写RESTful API。

发表评论

电子邮件地址不会被公开。