jquery返回数据不显示空格_每天用SpringBoot，还不懂RESTful API返回统一数据格式是怎么实现的？...

关于 Spring 的全局处理，我有两方面要说: 

1. 统一数据返回格式

2. 统一异常处理

为了将两个问题说明清楚，将分两个章节分别说明，本章主要说第一点

有童鞋说，我们项目都做了这种处理，就是在每个 API 都单独工具类将返回值进行封装，但这种不够优雅；我想写最少的代码完成这件事，也许有童鞋说，加几个注解就解决问题了，说的没错，但这篇文章主要是为了说明为什么加了几个注解就解决问题了，目的是希望大家知其所以然。

为了更好的说明问题，本文先说明如何实现，然后再详细剖析实现原理(这很关键)

为什么要做统一数据返回格式

前后端分离是当今服务形式的主流，如何设计一个好的 RESTful API ，以及如何让前端小伙伴可以处理标准的 response JSON 数据结构都至关重要，为了让前端有更好的逻辑展示与页面交互处理，每一次 RESTful 请求都应该包含以下几个信息:

名称	描述
status	状态码，标识请求成功与否，如 [1:成功；-1:失败]
errorCode	错误码，给出明确错误码，更好的应对业务异常；请求成功该值可为空
errorMsg	错误消息，与错误码相对应，更具体的描述异常信息
resultBody	返回结果，通常是 Bean 对象对应的 JSON 数据, 通常为了应对不同返回值类型，将其声明为泛型类型

实现

通用返回值类定义

根据上面的描述，用 Java Bean 来体现这个结构就是这样:

@Datapublic final class CommonResult<T> {    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<Object>{        @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<Object>(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 数据

继续添加 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 数据

添加一个返回值类型为 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 数据

解剖实现过程

我会将关键部分一一说明清楚，断案还需小伙伴自己去案发现场(打开自己的 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 接口，我在 Spring Bean 生命周期之“我从哪里来”？ 这篇文章中明确说明了 Spring Bean 初始化的几个关键，其中 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 做处理的

其实在 HttpMessageConverter是如何转换数据的？ 这篇文章中已经说明了一部分，希望小伙伴先看这篇文章，下面的部分就会秒懂了，我们在这里做进一步的说明

在 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<Object> {    @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  来处理不同类型的返回值

在类 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，我们来看类图:

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 方法，这才是真相!!!  回复「demo」获取完整代码

这是 RESTful API 正常返回内容的情况，下一篇文章，让我们来侦查一下统一异常情况的处理以及实现原理

灵魂追问

1. 返回值是非 ResponseEntity 类型时，用的是什么 handler？它支持的返回值类型是什么？看过你也许就知道为什么要用 @ResponseBody 注解了

2. 你有追踪过 DispatchServlet 的整个请求过程吗？

提高效率工具

JSON-Viewer

JSON-Viewer 是 Chrome 浏览器的插件，用于快速解析及格式化 json 内容，在 Chrome omnibox(多功能输入框)输入json-viewer + TAB ，将 json 内容拷贝进去，然后输入回车键，将看到结构清晰的 json 数据，同时可以自定义主题

另外，前端人员打开开发者工具，双击请求链接，会自动将 response 中的 json 数据解析出来，非常方便

---

SpringBoot Admin 使用指南

SpringBoot Kafka 整合使用

SpringBoot RabbitMQ 整合使用

Elasticsearch索引增量统计及定时邮件实现

Elasticsearch实战 | 必要的时候，还得空间换时间!
干货 |《从Lucene到Elasticsearch全文检索实战》拆解实践

JVM面试问题系列：JVM 配置常用参数和常用 GC 调优策略

Apache Flink 是如何管理好内存的？

ELK 实时日志分析平台环境搭建

干货 | Elasticsearch、Kibana数据导出实战

最详细的自定义Spring Boot Starter开发教程

Spring中的@Qualifier注解你会用吗

老司机教你通过Spring来读取文件的各种姿势

Java 8 Time Api 使用指南-珍藏限量版

右上角按钮分享给更多人哦~

我就知道你在看！

欢迎思想碰撞，点我留言交流

❤️「转发」和「在看」，是对我最大的支持❤️