01、背景介绍
熟悉 web 系统开发的同学可能比较熟悉,目前绝大多数的互联网软件平台基本都是前后端分离的开发模式,为了加快前后端接口对接速度,一套完善且规范的接口标准格式是非常有必要的,不仅能够提升开发效率,也会让代码看起来更加简洁、好维护。
今天这篇文章,我们一起来学习一下如何在 Spring Boot 中统一接口的返回数据格式。
02、定义数据返回格式
最常见的一种做法是封装一个工具类,在类中定义需要返回的字段信息,比如状态码、结果描述、结果数据集等,然后在接口中返回给客户端。
例如如下示例。
2.1、定义返回对象
2.2、定义状态码
2.3、统一返回格式
当请求http://localhost:8080/queryUser?userId=1地址时,返回结果示例如下:
前端根据code值来判断接口请求是否成功。
这种实现方式属于万能的一种方式,唯一的缺点就是重复编程工作很大,每个接口都要根据业务的要求进行不同程度的try..catch操作,如果有几百个接口,代码看起来会比较臃肿。
03、高级封装实现
Spring Boot 框架其实已经帮助开发者封装了很多实用的工具,比如ResponseBodyAdvice,我们可以利用来实现数据格式的统一返回。
简单的说,ResponseBodyAdvice可以对controller层中的拥有@ResponseBody注解属性的方法进行响应拦截,用户可以利用这一特性来封装数据的返回格式,也可以进行加密、签名等操作。
3.1、ResponseBodyAdvice 用法介绍
3.2、调整接口返回参数
此时,在controller层无需返回ResultMsg对象类型,直接改成对应的业务对象即可,示例如下:
在此请求接口地址,返回结果与上文一致。
3.3、字符串类型返回问题
假如返回的接口数据对象是字符串类型,比如如下示例:
先猜猜结果如下?
在浏览器中请求地址http://localhost:8080/hello,结果如下:
图片
抛出异常了!错误原因如下。
发生这个现象的原因在于:当接口返回的结果是String类型时,会优先使用StringHttpMessageConverter字符串消息转换器来响应数据,其次采用对象转换器。
因此我们需要对CustomerResponseAdvice进行改造,当返回的数据类型为String时,对其单独进行处理,示例如下:
启动服务后,再次请求地址,结果如下:
图片
从日志上可以清晰的看到,与预期一致!
**有个地方需要重点注意一下:默认String类型的数据响应给客户端的格式为text/html,为了统一响应格式,需要手动设置响应类型为json**。
3.4、全局异常处理
在上文的介绍中,当遇到异常时第一时间想到的是try...catch。其实大量的try...catch,不仅编程工作量很大,而且可读性也差。
在 Spring Boot 中,其实我们不用一个一个的去写,我们可以利用@ControllerAdvice和@ExceptionHandler注解实现全局异常处理器,拦截controller层抛出的异常,具体应用示例如下:
下面我们写一个异常接口来验证一下,代码如下:
启动服务后,在浏览器发起请求,返回结果如下:
04、小结
最后总结一下,在实际的项目开发过程中,统一响应格式通常有两种实现方式。
- 方式一:在接口层直接返回标准格式,同时通过全局异常处理器来捕捉并处理异常;
- 方式二:在接口层返回业务对象,通过实现ResponseBodyAdvice接口统一封装格式
如果不希望 Spring Boot 托管响应内容,要求编程风格统一,可以采用方式一;如果希望尽量简化业务代码的开发量,可以采用方式二。
这两种方式,项目开发中都有所应用,具体采用哪一种,通常以团队开发风格为主。
示例代码地址: