正文 

当前位置： 首页 > java > java框架

每天用springboot，还不懂restfulapi返回统一数据格式是怎么实现的？

     2022-04-03     440

关键词：

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

  1. 统一数据返回格式
  2. 统一异常处理
    为了将两个问题说明清楚，将分两个章节分别说明，本章主要说第一点

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

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

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

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

@Data
public 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
@Configuration
public 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<UserVo> getUserList(){
        List<UserVo> 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，那来看这个类吧:

@Configuration
public class DelegatingWebMvcConfiguration extends WebMvcConfigurationSupport {
    ...
}

有 @Configuration 注解，你应该很熟悉了，该类的父类 WebMvcConfigurationSupport 中却隐藏着一段关键代码:

@Bean
public RequestMappingHandlerAdapter requestMappingHandlerAdapter() {
    RequestMappingHandlerAdapter adapter = createRequestMappingHandlerAdapter();
    ...
    return adapter;
}

RequestMappingHandlerAdapter 是每一次请求处理的关键，来看该类的定义:

public class RequestMappingHandlerAdapter extends AbstractHandlerMethodAdapter
        implements BeanFactoryAware, InitializingBean {
    ...
}

该类实现了 InitializingBean 接口，我在 Spring Bean 生命周期之“我从哪里来”？ 这篇文章中明确说明了 Spring Bean 初始化的几个关键，其中 InitializingBean 接口的
afterPropertiesSet 方法就是关键之一，在 RequestMappingHandlerAdapter 类中同样重写了该方法:

@Override
public void afterPropertiesSet() {
    // Do this first, it may add ResponseBody advice beans
    initControllerAdviceCache();

    if (this.argumentResolvers == null) {
        List<HandlerMethodArgumentResolver> resolvers = getDefaultArgumentResolvers();
        this.argumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers);
    }
    if (this.initBinderArgumentResolvers == null) {
        List<HandlerMethodArgumentResolver> resolvers = getDefaultInitBinderArgumentResolvers();
        this.initBinderArgumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers);
    }
    if (this.returnValueHandlers == null) {
        List<HandlerMethodReturnValueHandler> handlers = getDefaultReturnValueHandlers();
        this.returnValueHandlers = new HandlerMethodReturnValueHandlerComposite().addHandlers(handlers);
    }
}

该方法内容都非常关键，但我们先来看 initControllerAdviceCache 方法，其他内容后续再单独说明:

private void initControllerAdviceCache() {
        ...
    if (logger.isInfoEnabled()) {
        logger.info("Looking for @ControllerAdvice: " + getApplicationContext());
    }

    List<ControllerAdviceBean> beans = ControllerAdviceBean.findAnnotatedBeans(getApplicationContext());
    AnnotationAwareOrderComparator.sort(beans);

    List<Object> requestResponseBodyAdviceBeans = new ArrayList<Object>();

    for (ControllerAdviceBean bean : beans) {
        ...
        if (ResponseBodyAdvice.class.isAssignableFrom(bean.getBeanType())) {
            requestResponseBodyAdviceBeans.add(bean);
        }
    }
}

通过 ControllerAdviceBean 静态方法扫描 ControllerAdvice注解，可是我们在实现上使用的是 @RestControllerAdvice注解，打开看该注解:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@ControllerAdvice
@ResponseBody
public @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 <T> 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<T>) advice).beforeBodyWrite((T) body, returnType,
                        contentType, converterType, request, response);
            }
        }
        return body;
    }
}

我们重写的 beforeBodyWrite 方法终究会被调用到，真相就是这样了!!!

其实还没完，你有没有想过，如果我们的 API 方法返回值是 org.springframework.http.ResponseEntity<T> 类型，我们可以指定 HTTP 返回状态码，但是这个返回值会直接放到我们的 beforeBodyWrite 方法的 body 参数中吗？如果这样做很明显是错误的，因为 ResponseEntity 包含很多我们非业务数据在里面，那 Spring 是怎么帮我们处理的呢？

在我们方法取得返回值并且在调用 beforeBodyWrite 方法之前，还要选择 HandlerMethodReturnValueHandler 来处理不同类型的返回值

在类 HandlerMethodReturnValueHandlerComposite 中的 handleReturnValue 方法中

@Override
public 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 类型:

@Override
public boolean supportsParameter(MethodParameter parameter) {
    return (HttpEntity.class == parameter.getParameterType() ||
            RequestEntity.class == parameter.getParameterType());
}

所以当我们返回的类型为 ResponseEntity 时，就要通过 HttpEntityMethodProcessor 的 handleReturnValue 方法来处理我们的结果:

@Override
public 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 正常返回内容的情况，下一篇文章，让我们来侦查一下统一异常情况的处理以及实现原理

灵魂追问
返回值是非 ResponseEntity 类型时，用的是什么 handler？它支持的返回值类型是什么？看过你也许就知道为什么要用 @ResponseBody 注解了
你有追踪过 DispatchServlet 的整个请求过程吗？
提高效率工具
技术图片

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

技术图片

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

推荐阅读

  • 只会用 git pull ？有时候你可以尝试更优雅的处理方式
  • 双亲委派模型：大厂高频面试题，轻松搞定
  • 面试还不知道BeanFactory和ApplicationContext的区别？
  • 如何设计好的RESTful API
  • 程序猿为什么要看源码？
    欢迎持续关注公众号：「日拱一兵」
  • 前沿 Java 技术干货分享
  • 高效工具汇总 | 回复「工具」
  • 面试问题分析与解答
  • 技术资料领取 | 回复「资料」
    以读侦探小说思维轻松趣味学习 Java 技术栈相关知识，本着将复杂问题简单化，抽象问题具体化和图形化原则逐步分解技术问题，技术持续更新，请持续关注......

技术图片

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

tan日拱一兵
转发在看也很赞
喜欢作者

对于编程和软件工程我还不懂的问题

VSCode里Git有什么用？百科：“分布式相比于集中式的最大区别在于开发者可以提交到本地，每个开发者通过克隆（gitclone），在本地机器上拷贝一个完整的Git仓库。”网博：“用了git最方便的就是比如在公司写了很多代码后回到... 查看详情

html？这些还不懂咋办？

 1.什么是空白折叠现象？为什么要空白折叠呢？　　对于我们大多数人的习惯来讲，大都喜欢利用空格或者换行来调整文章的文字结构。这样往往可以使我们可以更轻松的阅读。但是，在HTML中却不允许我们这么做，这是为什... 查看详情

计算机408看不懂？那是你还不知道这套学习方法和资源

前言《数据结构》、《操作系统》、《计算机组成原理》和《计算机网络》这4门课程（俗称408）对于学计算机的人来说至关重要，不管你是考研还是找工作都会用得到。不管你现在的开发工作是否用得到它们，这... 查看详情

还不懂android的触摸反馈机制(代码片段)

当我们的手指从触摸屏幕上的各种View，开始到这个点击事件的结束到底经历了什么，我们来详细分析下。事件类型触摸事件会有三种类型：intaction=MotionEventCompat.getActionMasked(event);switch(action)caseMotionEvent.ACTION_DOWN:brea... 查看详情

3年经验，还不懂大事务问题？

https://blog.csdn.net/qq_28165595/article/details/120249607?utm_medium=distribute.pc_relevant.none-task-blog-2~default~baidujs_baidulandingword~default-0-120249607-blog-96501679.235^v35^pc_relevant_increate_t0_download_v2&spm=1001.2101.3001.4242.1&utm_relevant_index=1https://github.com/godma... 查看详情

springbootrestfulapi返回统一数据格式还不懂？

关于Spring的全局处理，有两方面要说:统一数据返回格式统一异常处理为了将两个问题说明清楚，将分两个章节分别说明，本章主要说第一点有童鞋说，我们项目都做了这种处理，就是在每个API都单独工具类将返回值进行封装，... 查看详情

2021最新java笔试题目，你不懂还不学？

第一家是美团美团的话，三面下来，设计的内容知识也是挺广的吧，有MySQL、Redis、Kafka、线程、算法、+、volatile、线程、并发、设计模式等等…一面问题：MySQL+Redis+Kafka+线程+算法mysql知道哪些存储... 查看详情

云原生时代，你还不懂gitops？

云原生时代，你还不懂GitOps？GitOps：又一次造词运动？伴随着DevOps在近些年的火爆，围绕xOps产生了很多概念，诸如DevSecOps，AIOps，MLOps，ChatOps等等，当然还有今天讲述的主角GitOps。人们在xOps... 查看详情

动态规划不信看完你还不懂动态规划(代码片段)

1.什么是动态规划？维基百科：动态规划(Dynamicprogramming，简称DP)是一种通过把原问题分解为相对简单的子问题的方式求解复杂问题的方法。使用场景：动态规划常常适用于有重叠子问题和最优子结构性质的问题。d... 查看详情

动态规划不信看完你还不懂动态规划(代码片段)

1.什么是动态规划？维基百科：动态规划(Dynamicprogramming，简称DP)是一种通过把原问题分解为相对简单的子问题的方式求解复杂问题的方法。使用场景：动态规划常常适用于有重叠子问题和最优子结构性质的问题。d... 查看详情

只会懒汉式和饿汉式你还不懂单例模式!(代码片段)

只会懒汉式和饿汉式你还不懂单例模式!一.文章导读设计模式是每一位技术人员都应该掌握的技术,但是现在根据实际情况来看,大家对于设计模式也仅仅限于面试八股文,知其然不知其所以然。你说设计模式很难吧,其实也没有,你... 查看详情

前端面试还不懂这些技巧？看完跳槽少说涨50%(下）

本文分成了上下两篇：前端面试还不懂这些技巧？看完跳槽少说涨50%(上）二、面试前的准备1.利用脑图来梳理知识点对于统一校招类的面试，要重点梳理前端的所有知识点，校招面试一般是为了做人才储备ÿ... 查看详情

还不懂shell脚本核心？这一篇就够了。(代码片段)

 前言：现在在我们已经知道了Linux系统和命令行的基础知识，是时候开始编程了。本章讨论编写shell脚本的基础知识。在开始编写自己的shell脚本前，你必须了解的基本概念都在这里。 一、多个shell命令的使用shell脚... 查看详情

还不懂shell脚本核心？这一篇就够了。(代码片段)

 前言：现在在我们已经知道了Linux系统和命令行的基础知识，是时候开始编程了。本章讨论编写shell脚本的基础知识。在开始编写自己的shell脚本前，你必须了解的基本概念都在这里。 一、多个shell命令的使用shell脚... 查看详情

这都2021年了还不懂linux？一张思维导图帮你理清思路！建议收藏！

Linux思维导图Linux常用命令Linux网络配置Linux进程管理Linux服务管理只用一张图即可理清思路!!!长图加载有点慢，双击即可看到！持续更新中~~~~需要xmind文件评论区留下邮箱我分享给你！ 查看详情

如果看了此文你还不懂傅里叶变换，那就过来掐死我吧完整版

如果看了此文你还不懂傅里叶变换，那就过来掐死我吧【完整版】转自 https://blog.csdn.net/u012361418/article/details/46277779 还记得上大学的时候的机械振动还有工程测试利用的傅立叶变化，当时感觉云里雾里的，感觉好难，也就... 查看详情

看完这篇还不懂链表你来打我(代码片段)

????????关注后回复 “进群” ，拉你进程序员交流群????????作者丨码农的荒岛求生来源丨码农的荒岛求生（ID：escape-it）大家好，我是小风哥。链表是计算机科学中极其经典的一种数据结构，那么作为程序... 查看详情

你还不懂jvm垃圾回收及收集器么？(代码片段)

Serial收集器这个收集器是一个单线程工作的收集器，但它的“单线程”的意义并不仅仅是说明它只会使用一个处理器或一条收集线程去完成垃圾收集工作，更重要的是强调在它进行垃圾收集时，必须暂停其他所有工作... 查看详情