web返回的数据集格式_SpringBoot RESTful API返回统一数据格式还不懂?
关于 Spring 的全局处理,我有两方面要说:
- 统一数据返回格式
- 统一异常处理
- 为了将两个问题说明清楚,将分两个章节分别说明,本章主要说第一点
有童鞋说,我们项目都做了这种处理,就是在每个 API 都单独工具类将返回值进行封装,但这种不够优雅;我想写最少的代码完成这件事,也许有童鞋说,加几个注解就解决问题了,说的没错,但这篇文章主要是为了说明为什么加了几个注解就解决问题了,目的是希望大家知其所以然。
![](/assets/blank.gif)
为了更好的说明问题,本文先说明如何实现,然后再详细剖析实现原理(这很关键)
为什么要做统一数据返回格式
前后端分离是当今服务形式的主流,如何让前端小伙伴可以处理标准的 response JSON 数据结构都至关重要,为了让前端有更好的逻辑展示与页面交互处理,每一次 RESTful 请求都应该包含以下几个信息:
名称
描述
status
状态码,标识请求成功与否,如 [1:成功;-1:失败]
errorCode
错误码,给出明确错误码,更好的应对业务异常;请求成功该值可为空
errorMsg
错误消息,与错误码相对应,更具体的描述异常信息
resultBody
返回结果,通常是 Bean 对象对应的 JSON 数据, 通常为了应对不同返回值类型,将其声明为泛型类型 实现
通用返回值类定义
根据上面的描述,用 Java Bean 来体现这个结构就是这样:
@Datapublic final class CommonResult { private int status = 1; private String errorCode = ""; private String errorMsg = ""; private T resultBody; public CommonResult() { } public CommonResult(T resultBody) { this.resultBody = resultBody; }}
配置
没错,我们需要借助几个关键注解来完成一下相关配置:
@EnableWebMvc@Configurationpublic class UnifiedReturnConfig { @RestControllerAdvice("com.example.unifiedreturn.api") static class CommonResultResponseAdvice implements ResponseBodyAdvice{ @Override public boolean supports(MethodParameter methodParameter, Class extends HttpMessageConverter>> aClass) { return true; } @Override public Object beforeBodyWrite(Object body, MethodParameter methodParameter, MediaType mediaType, Class extends HttpMessageConverter>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) { if (body instanceof CommonResult){ return body; } return new CommonResult(body); } }}
到这里就结束了,我们就可以纵情的写任何 RESTful API 了,所有的返回值都会有统一的 JSON 结构
测试
新建 UserController,添加相应的 RESTful API,测试用例写的比较简单,只为了说明返回值的处理
@RestController@RequestMapping("/users")public class UserController { @GetMapping("") public List getUserList(){ List userVoList = Lists.newArrayListWithCapacity(2); userVoList.add(UserVo.builder().id(1L).name("日拱一兵").age(18).build()); userVoList.add(UserVo.builder().id(2L).name("tan").age(19).build()); return userVoList; }}
打开浏览器输入地址测试: http://localhost:8080/users/ ,我们可以看到返回了 List JSON 数据
![](/assets/blank.gif)
继续添加 RESTful API,根据用户 ID 查询用户信息
@GetMapping("/{id}")public UserVo getUserByName(@PathVariable Long id){ return UserVo.builder().id(1L).name("日拱一兵").age(18).build();}
打开浏览器输入地址测试: http://localhost:8080/users/1 ,我们可以看到返回了单个 User JSON 数据
![](/assets/blank.gif)
添加一个返回值类型为 ResponseEntity 的 API
@GetMapping("/testResponseEntity")public ResponseEntity getUserByAge(){ return new ResponseEntity(UserVo.builder().id(1L).name("日拱一兵").age(18).build(), HttpStatus.OK);}
打开浏览器输入地址测试: http://localhost:8080/users/testResponseEntity ,我们可以看到同样返回了单个 User JSON 数据
![](/assets/blank.gif)
解剖实现过程
我会将关键部分一一说明清楚,断案还需小伙伴自己去案发现场(打开自己的 IDE 查看)
故事要从 @EnableWebMvc 这个注解说起,打开该注解看:
@Retention(RetentionPolicy.RUNTIME)@Target(ElementType.TYPE)@Documented@Import(DelegatingWebMvcConfiguration.class)public @interface EnableWebMvc {}
通过 @Import 注解引入了 DelegatingWebMvcConfiguration.class,那来看这个类吧:
@Configurationpublic class DelegatingWebMvcConfiguration extends WebMvcConfigurationSupport { ...}
有 @Configuration 注解,你应该很熟悉了,该类的父类 WebMvcConfigurationSupport 中却隐藏着一段关键代码:
@Beanpublic RequestMappingHandlerAdapter requestMappingHandlerAdapter() { RequestMappingHandlerAdapter adapter = createRequestMappingHandlerAdapter(); ... return adapter;}
RequestMappingHandlerAdapter 是每一次请求处理的关键,来看该类的定义:
public class RequestMappingHandlerAdapter extends AbstractHandlerMethodAdapter implements BeanFactoryAware, InitializingBean { ...}
该类实现了 InitializingBean 接口,其中 InitializingBean 接口的afterPropertiesSet 方法就是关键之一,在 RequestMappingHandlerAdapter 类中同样重写了该方法:
@Overridepublic void afterPropertiesSet() { // Do this first, it may add ResponseBody advice beans initControllerAdviceCache(); if (this.argumentResolvers == null) { List resolvers = getDefaultArgumentResolvers(); this.argumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers); } if (this.initBinderArgumentResolvers == null) { List resolvers = getDefaultInitBinderArgumentResolvers(); this.initBinderArgumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers); } if (this.returnValueHandlers == null) { List handlers = getDefaultReturnValueHandlers(); this.returnValueHandlers = new HandlerMethodReturnValueHandlerComposite().addHandlers(handlers); }}
该方法内容都非常关键,但我们先来看 initControllerAdviceCache 方法,其他内容后续再单独说明:
private void initControllerAdviceCache() { ... if (logger.isInfoEnabled()) { logger.info("Looking for @ControllerAdvice: " + getApplicationContext()); } List beans = ControllerAdviceBean.findAnnotatedBeans(getApplicationContext()); AnnotationAwareOrderComparator.sort(beans); List requestResponseBodyAdviceBeans = new ArrayList(); for (ControllerAdviceBean bean : beans) { ... if (ResponseBodyAdvice.class.isAssignableFrom(bean.getBeanType())) { requestResponseBodyAdviceBeans.add(bean); } }}
通过 ControllerAdviceBean 静态方法扫描 ControllerAdvice 注解,可是我们在实现上使用的是 @RestControllerAdvice 注解,打开看该注解:
@Target(ElementType.TYPE)@Retention(RetentionPolicy.RUNTIME)@Documented@ControllerAdvice@ResponseBodypublic @interface RestControllerAdvice {
该注解由 @ControllerAdvice 和 @ResponseBody 标记,就好比你熟悉的 @RestController 注解由 @Controller 和 @ResponseBody 标记是一样的
到这里你已经知道我们用 @RestControllerAdvice 标记的 Bean 是如何被加载到 Spring 上下文的,接下来就要知道是 Spring 是如何使用我们的 bean 以及对返回 body 做处理的
在 AbstractMessageConverterMethodProcessor 的 writeWithMessageConverters 方法中,有一段核心代码:
if (messageConverter instanceof GenericHttpMessageConverter) { if (((GenericHttpMessageConverter) messageConverter).canWrite( declaredType, valueType, selectedMediaType)) { outputValue = (T) getAdvice().beforeBodyWrite(outputValue, returnType, selectedMediaType, (Class extends HttpMessageConverter>>) messageConverter.getClass(), inputMessage, outputMessage); ... return; }}
可以看到通过 getAdvice() 调用了 beforeBodyWrite 方法,我们已经接近真相了
protected RequestResponseBodyAdviceChain getAdvice() { return this.advice;}
RequestResponseBodyAdviceChain,看名字带有 Chain,很明显用到了责任链设计模式,只不过它传递责任链以循环的方式完成:
class RequestResponseBodyAdviceChain implements RequestBodyAdvice, ResponseBodyAdvice { @Override public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType contentType, Class extends HttpMessageConverter>> converterType, ServerHttpRequest request, ServerHttpResponse response) { return processBody(body, returnType, contentType, converterType, request, response); } @SuppressWarnings("unchecked") private Object processBody(Object body, MethodParameter returnType, MediaType contentType, Class extends HttpMessageConverter>> converterType, ServerHttpRequest request, ServerHttpResponse response) { for (ResponseBodyAdvice> advice : getMatchingAdvice(returnType, ResponseBodyAdvice.class)) { if (advice.supports(returnType, converterType)) { body = ((ResponseBodyAdvice) advice).beforeBodyWrite((T) body, returnType, contentType, converterType, request, response); } } return body; }}
我们重写的 beforeBodyWrite 方法终究会被调用到,真相就是这样了!!!
其实还没完,你有没有想过,如果我们的 API 方法返回值是 org.springframework.http.ResponseEntity 类型,我们可以指定 HTTP 返回状态码,但是这个返回值会直接放到我们的 beforeBodyWrite 方法的 body 参数中吗?如果这样做很明显是错误的,因为 ResponseEntity 包含很多我们非业务数据在里面,那 Spring 是怎么帮我们处理的呢?
在我们方法取得返回值并且在调用 beforeBodyWrite 方法之前,还要选择 HandlerMethodReturnValueHandler 用于处理不同的 Handler 来处理返回值
在类 HandlerMethodReturnValueHandlerComposite 中的 handleReturnValue 方法中
@Overridepublic void handleReturnValue(Object returnValue, MethodParameter returnType, ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception { HandlerMethodReturnValueHandler handler = selectHandler(returnValue, returnType); if (handler == null) { throw new IllegalArgumentException("Unknown return value type: " + returnType.getParameterType().getName()); } handler.handleReturnValue(returnValue, returnType, mavContainer, webRequest);}
通过调用 selectHandler 方法来选择合适的 handler,Spring 内置了很多个 Handler,我们来看类图:
![](/assets/blank.gif)
HttpEntityMethodProcessor 就是其中之一,它重写了 supportsParameter 方法,支持 HttpEntity 类型,即支持 ResponseEntity 类型:
@Overridepublic boolean supportsParameter(MethodParameter parameter) { return (HttpEntity.class == parameter.getParameterType() || RequestEntity.class == parameter.getParameterType());}
所以当我们返回的类型为 ResponseEntity 时,就要通过 HttpEntityMethodProcessor 的 handleReturnValue 方法来处理我们的结果:
@Overridepublic void handleReturnValue(Object returnValue, MethodParameter returnType, ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception { ... if (responseEntity instanceof ResponseEntity) { int returnStatus = ((ResponseEntity>) responseEntity).getStatusCodeValue(); outputMessage.getServletResponse().setStatus(returnStatus); if (returnStatus == 200) { if (SAFE_METHODS.contains(inputMessage.getMethod()) && isResourceNotModified(inputMessage, outputMessage)) { // Ensure headers are flushed, no body should be written. outputMessage.flush(); // Skip call to converters, as they may update the body. return; } } } // Try even with null body. ResponseBodyAdvice could get involved. writeWithMessageConverters(responseEntity.getBody(), returnType, inputMessage, outputMessage); // Ensure headers are flushed even if no body was written. outputMessage.flush();}
该方法提取出 responseEntity.getBody(),并传递个 MessageConverter,然后再继续调用 beforeBodyWrite 方法,这才是真相!!!
这是 RESTful API 正常返回内容的情况,下一篇文章,让我们来侦查一下统一异常情况的处理以及实现原理
灵魂追问
- 返回值是非 ResponseEntity 类型时,用的是什么 handler?它支持的返回值类型是什么?看过你也许就知道为什么要用 @ResponseBody 注解了
- 你有追踪过 DispatchServlet 的整个请求过程吗?
web返回的数据集格式_SpringBoot RESTful API返回统一数据格式还不懂?相关推荐
- vue安装Postcss_Flask和Vue.js构建全栈单页面web应用【通过Flask开发RESTful API】
前言: 看了一些国外的关于介绍flask和vue的前后端分离的文章,但没看到比较通俗易懂,代码完善的,直到昨天看到一篇新出的文章,而且内容非常棒,所以翻译过来,供大家一起学习. 原文来自Develop ...
- Restful Api 写法——统一返回值
记录Restful Api 自定义统一返回值方式! 以下为示例代码: Code码Java类 package *.*.*;import java.util.ArrayList; import java. ...
- Java Web学习总结(43)—— Restful API 版本控制
在实际项目开发中我们经常需要对接口进行版本管理.那今天我们就来聊聊为什么需要版本控制,以及如何对REST API进行版本控制.我们将讨论4种版本控制的方法,并比较不同的方法. 为什么我们需要对REST ...
- web返回的数据集格式_200G倾斜数据无插件web端预览!兼容三端,有容乃大—MapGIS M3D数据格式...
"有容乃大"最早见之于明代兵部尚书太子太保袁可立在河南睢州自己"弗过堂"中所著的自勉联.二百年后又有清末民族英雄林则徐题于书室的八字联:"海纳百川,有 ...
- 无返回值_只需一步,在Spring Boot中统一Restful API返回值格式与处理异常
统一返回值 在前后端分离大行其道的今天,有一个统一的返回值格式不仅能使我们的接口看起来更漂亮,而且还可以使前端可以统一处理很多东西,避免很多问题的产生. 比较通用的返回值格式如下: public cl ...
- 使用 Swagger 文档化和定义 RESTful API
大部分 Web 应用程序都支持 RESTful API,但不同于 SOAP API--REST API 依赖于 HTTP 方法,缺少与 Web 服务描述语言(Web Services Descript ...
- Restful API 中的错误处理方案
简介 随着移动开发和前端开发的崛起,越来越多的 Web 后端应用都倾向于实现 Restful API. Restful API 是一个简单易用的前后端分离方案,它只需要对客户端请求进行处理,然后返回结 ...
- 使用ASP.NET Core 3.x 构建 RESTful API - 3.4 内容协商
现在,当谈论起 RESTful Web API 的时候,人们总会想到 JSON.但是实际上,JSON 和 RESTful API 没有半毛钱关系,只不过 JSON 恰好是RESTful API 结果的 ...
- 如何设计好的RESTful API?
REST架构风格最初由Roy T. Fielding(HTTP/1.1协议专家组负责人)在其2000年的博士学位论文中提出.HTTP就是该架构风格的一个典型应用.从其诞生之日开始,它就因其可扩展性和简 ...
最新文章
- ASP.NET中的AdRotator控件即广告控件的使用
- 调用百度报Cannot read property ‘lng‘ of null错误
- springMVC-配置Bean
- [JavaWeb-JavaScript]JavaScript运算符
- 高仿人人Android梦想版终极源码发送(转)
- 如何选择适合你的企业数据管理类产品
- 解决浏览器跨域加载本地文件报错 Access to script at ‘xxx‘ from origin ‘null‘ has been blocked by CORS policy
- 支持蓝牙的模拟器_PM 2032电池模拟器展会现场演示
- php自带解压缩,PHP自带ZIP压缩、解压缩类ZipArchiv使用指南_PHP教程
- 蓝桥杯2018年第九届C/C++省赛B组第二题-明码
- WP:当文档中有阿拉伯文(维文)时,文字布局很麻烦
- 达梦数据库(DM)——SQL美化器不是plsq独有的功能,达梦manage客户端管理工具可以
- sha256算法细节详解
- Win7 便签设置字体方法
- python建模全步骤
- 黑龙江小兴安岭林区停伐后上演“王者归来”
- 四位达林顿_达林顿管的四种接法与常用型号
- 未来智能家居方向是什么模式?小米?华为?智汀?
- VSP编译工具链安装
- IT华人在硅谷的一天