您当前的位置:首页 > 电脑百科 > 程序开发 > 框架

Spring Boot 中如何统一 API 接口响应格式?

时间:2021-03-24 15:36:12  来源:  作者:

今天又要给大家介绍一个 Spring Boot 中的组件
--HandlerMethodReturnValueHandler。

在前面的文章中(如何优雅的实现 Spring Boot 接口参数加密解密?),松哥已经和大家介绍过如何对请求/响应数据进行预处理/二次处理,当时我们使用了 ResponseBodyAdvice 和 RequestBodyAdvice。其中 ResponseBodyAdvice 可以实现对响应数据的二次处理,可以在这里对响应数据进行加密/包装等等操作。不过这不是唯一的方案,今天松哥要和大家介绍一种更加灵活的方案--HandlerMethodReturnValueHandler,我们一起来看看下。

1.HandlerMethodReturnValueHandler

HandlerMethodReturnValueHandler 的作用是对处理器的处理结果再进行一次二次加工,这个接口里边有两个方法:

public interface HandlerMethodReturnValueHandler {
 boolean supportsReturnType(MethodParameter returnType);
 void handleReturnValue(@Nullable Object returnValue, MethodParameter returnType,
   ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception;
}
  • supportsReturnType:这个处理器是否支持相应的返回值类型。
  • handleReturnValue:对方法返回值进行处理。

HandlerMethodReturnValueHandler 有很多默认的实现类,我们来看下:

Spring Boot 中如何统一 API 接口响应格式?

 

接下来我们来把这些实现类的作用捋一捋:

ViewNameMethodReturnValueHandler

这个处理器用来处理返回值为 void 和 String 的情况。如果返回值为 void,则不做任何处理。如果返回值为 String,则将 String 设置给 mavContainer 的 viewName 属性,同时判断这个 String 是不是重定向的 String,如果是,则设置 mavContainer 的 redirectModelScenario 属性为 true,这是处理器返回重定向视图的标志。

ViewMethodReturnValueHandler

这个处理器用来处理返回值为 View 的情况。如果返回值为 View,则将 View 设置给 mavContainer 的 view 属性,同时判断这个 View 是不是重定向的 View,如果是,则设置 mavContainer 的 redirectModelScenario 属性为 true,这是处理器返回重定向视图的标志。

MapMethodProcessor

这个处理器用来处理返回值类型为 Map 的情况,具体的处理方案就是将 map 添加到 mavContainer 的 model 属性中。

StreamingResponseBodyReturnValueHandler

这个用来处理 StreamingResponseBody 或者 ResponseEntity<StreamingResponseBody> 类型的返回值。

DeferredResultMethodReturnValueHandler

这个用来处理 DeferredResult、ListenableFuture 以及 CompletionStage 类型的返回值,用于异步请求。

CallableMethodReturnValueHandler

处理 Callable 类型的返回值,也是用于异步请求。

HttpHeadersReturnValueHandler

这个用来处理 HttpHeaders 类型的返回值,具体处理方式就是将 mavContainer 中的 requestHandled 属性设置为 true,该属性是请求是否已经处理完成的标志(如果处理完了,就到此为止,后面不会再去找视图了),然后将 HttpHeaders 添加到响应头中。

ModelMethodProcessor

这个用来处理返回值类型为 Model 的情况,具体的处理方式就是将 Model 添加到 mavContainer 的 model 上。

ModelAttributeMethodProcessor

这个用来处理添加了 @ModelAttribute 注解的返回值类型,如果 annotaionNotRequired 属性为 true,也可以用来处理其他非通用类型的返回值。

ServletModelAttributeMethodProcessor

同上,该类只是修改了参数解析方式。

ResponseBodyEmitterReturnValueHandler

这个用来处理返回值类型为 ResponseBodyEmitter 的情况。

ModelAndViewMethodReturnValueHandler

这个用来处理返回值类型为 ModelAndView 的情况,将返回值中的 Model 和 View 分别设置到 mavContainer 的相应属性上去。

ModelAndViewResolverMethodReturnValueHandler

这个的 supportsReturnType 方法返回 true,即可以处理所有类型的返回值,这个一般放在最后兜底。

AbstractMessageConverterMethodProcessor

这是一个抽象类,当返回值需要通过 HttpMessageConverter 进行转化的时候会用到它的子类。这个抽象类主要是定义了一些工具方法。

RequestResponseBodyMethodProcessor

这个用来处理添加了 @ResponseBody 注解的返回值类型。

HttpEntityMethodProcessor

这个用来处理返回值类型是 HttpEntity 并且不是 RequestEntity 的情况。

AsyncHandlerMethodReturnValueHandler

这是一个空接口,暂未发现典型使用场景。

AsyncTaskMethodReturnValueHandler

这个用来处理返回值类型为 WebAsyncTask 的情况。

HandlerMethodReturnValueHandlerComposite

看 Composite 就知道,这是一个组合处理器,没啥好说的。

这个就是系统默认定义的 HandlerMethodReturnValueHandler。

那么在上面的介绍中,大家看到反复涉及到一个组件 mavContainer,这个我也要和大家介绍一下。

2.ModelAndViewContainer

ModelAndViewContainer 就是一个数据穿梭巴士,在整个请求的过程中承担着数据传送的工作,从它的名字上我们可以看出来它里边保存着 Model 和 View 两种类型的数据,但是实际上可不止两种,我们来看下 ModelAndViewContainer 的定义:

public class ModelAndViewContainer {
 private boolean ignoreDefaultModelOnRedirect = false;
 @Nullable
 private Object view;
 private final ModelMap defaultModel = new BindingAwareModelMap();
 @Nullable
 private ModelMap redirectModel;
 private boolean redirectModelScenario = false;
 @Nullable
 private HttpStatus status;
 private final Set<String> noBinding = new HashSet<>(4);
 private final Set<String> bindingDisabled = new HashSet<>(4);
 private final SessionStatus sessionStatus = new SimpleSessionStatus();
 private boolean requestHandled = false;
}

把这几个属性理解了,基本上也就整明白 ModelAndViewContainer 的作用了:

  • defaultModel:默认使用的 Model。当我们在接口参数重使用 Model、ModelMap 或者 Map 时,最终使用的实现类都是 BindingAwareModelMap,对应的也都是 defaultModel。
  • redirectModel:重定向时候的 Model,如果我们在接口参数中使用了 RedirectAttributes 类型的参数,那么最终会传入 redirectModel。

可以看到,一共有两个 Model,两个 Model 到底用哪个呢?这个在 getModel 方法中根据条件返回合适的 Model:

public ModelMap getModel() {
 if (useDefaultModel()) {
  return this.defaultModel;
 }
 else {
  if (this.redirectModel == null) {
   this.redirectModel = new ModelMap();
  }
  return this.redirectModel;
 }
}
private boolean useDefaultModel() {
 return (!this.redirectModelScenario || (this.redirectModel == null && !this.ignoreDefaultModelOnRedirect));
}

这里 redirectModelScenario 表示处理器是否返回 redirect 视图;ignoreDefaultModelOnRedirect 表示是否在重定向时忽略 defaultModel,所以这块的逻辑是这样:

  1. 如果 redirectModelScenario 为 true,即处理器返回的是一个重定向视图,那么使用 redirectModel。如果 redirectModelScenario 为 false,即处理器返回的不是一个重定向视图,那么使用 defaultModel。
  2. 如果 redirectModel 为 null,并且 ignoreDefaultModelOnRedirect 为 false,则使用 redirectModel,否则使用 defaultModel。

接下来还剩下如下一些参数:

  • view:返回的视图。
  • status:HTTP 状态码。
  • noBinding:是否对 @ModelAttribute(binding=true/false) 声明的数据模型的相应属性进行绑定。
  • bindingDisabled:不需要进行数据绑定的属性。
  • sessionStatus:SessionAttribute 使用完成的标识。
  • requestHandled:请求处理完成的标识(例如添加了 @ResponseBody 注解的接口,这个属性为 true,请求就不会再去找视图了)。

这个 ModelAndViewContainer 小伙伴们权且做一个了解,松哥在后面的源码分析中,还会和大家再次聊到这个组件。

接下来我们也来自定义一个 HandlerMethodReturnValueHandler,来感受一下 HandlerMethodReturnValueHandler 的基本用法。

3.API 接口数据包装

假设我有这样一个需求:我想在原始的返回数据外面再包裹一层,举个简单例子,本来接口是下面这样:

@RestController
public class UserController {
    @GetMApping("/user")
    public User getUserByUsername(String username) {
        User user = new User();
        user.setUsername(username);
        user.setAddress("www.JAVAboy.org");
        return user;
    }
}

返回的数据格式是下面这样:

{"username":"javaboy","address":"www.javaboy.org"}

现在我希望返回的数据格式变成下面这样:

{"status":"ok","data":{"username":"javaboy","address":"www.javaboy.org"}}

就这样一个简单需求,我们一起来看下怎么实现。

3.1 RequestResponseBodyMethodProcessor

在开始定义之前,先给大家介绍一下 RequestResponseBodyMethodProcessor,这是 HandlerMethodReturnValueHandler 的实现类之一,这个主要用来处理返回 JSON 的情况。

我们来稍微看下:

@Override
public boolean supportsReturnType(MethodParameter returnType) {
 return (AnnotatedElementUtils.hasAnnotation(returnType.getContainingClass(), ResponseBody.class) ||
   returnType.hasMethodAnnotation(ResponseBody.class));
}
@Override
public void handleReturnValue(@Nullable Object returnValue, MethodParameter returnType,
  ModelAndViewContainer mavContainer, NativeWebRequest webRequest)
  throws IOException, HttpMediaTypeNotAcceptableException, HttpMessageNotWritableException {
 mavContainer.setRequestHandled(true);
 ServletServerHttpRequest inputMessage = createInputMessage(webRequest);
 ServletServerHttpResponse outputMessage = createOutputMessage(webRequest);
 writeWithMessageConverters(returnValue, returnType, inputMessage, outputMessage);
}
  • supportsReturnType:从这个方法中可以看到,这里支持有 @ResponseBody 注解的接口。
  • handleReturnValue:这是具体的处理逻辑,首先 mavContainer 中设置 requestHandled 属性为 true,表示这里处理完成后就完了,以后不用再去找视图了,然后分别获取 inputMessage 和 outputMessage,调用 writeWithMessageConverters 方法进行输出,writeWithMessageConverters 方法是在父类中定义的方法,这个方法比较长,核心逻辑就是调用确定输出数据、确定 MediaType,然后通过 HttpMessageConverter 将 JSON 数据写出去即可。

有了上面的知识储备之后,接下来我们就可以自己实现了。

3.2 具体实现

首先自定义一个 HandlerMethodReturnValueHandler:

public class MyHandlerMethodReturnValueHandler implements HandlerMethodReturnValueHandler {
    private HandlerMethodReturnValueHandler handler;

    public MyHandlerMethodReturnValueHandler(HandlerMethodReturnValueHandler handler) {
        this.handler = handler;
    }

    @Override
    public boolean supportsReturnType(MethodParameter returnType) {
        return handler.supportsReturnType(returnType);
    }

    @Override
    public void handleReturnValue(Object returnValue, MethodParameter returnType, ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {
        Map<String, Object> map = new HashMap<>();
        map.put("status", "ok");
        map.put("data", returnValue);
        handler.handleReturnValue(map, returnType, mavContainer, webRequest);
    }
}

由于我们要做的功能其实是在 RequestResponseBodyMethodProcessor 基础之上实现的,因为支持 @ResponseBody,输出 JSON 那些东西都不变,我们只是在输出之前修改一下数据而已。所以我这里直接定义了一个属性 HandlerMethodReturnValueHandler,这个属性的实例就是 RequestResponseBodyMethodProcessor,supportsReturnType 方法就按照 RequestResponseBodyMethodProcessor 的要求来,在 handleReturnValue 方法中,我们先对返回值进行一个预处理,然后调用 RequestResponseBodyMethodProcessor#handleReturnValue 方法继续输出 JSON 即可。

接下来就是配置 MyHandlerMethodReturnValueHandler 使之生效了。由于 SpringMVC 中 HandlerAdapter 在加载的时候已经配置了 HandlerMethodReturnValueHandler(这块松哥以后会和大家分析相关源码),所以我们可以通过如下方式对已经配置好的 RequestMappingHandlerAdapter 进行修改,如下:

@Configuration
public class ReturnValueConfig implements InitializingBean {
    @Autowired
    RequestMappingHandlerAdapter requestMappingHandlerAdapter;
    @Override
    public void afterPropertiesSet() throws Exception {
        List<HandlerMethodReturnValueHandler> originHandlers = requestMappingHandlerAdapter.getReturnValueHandlers();
        List<HandlerMethodReturnValueHandler> newHandlers = new ArrayList<>(originHandlers.size());
        for (HandlerMethodReturnValueHandler originHandler : originHandlers) {
            if (originHandler instanceof RequestResponseBodyMethodProcessor) {
                newHandlers.add(new MyHandlerMethodReturnValueHandler(originHandler));
            }else{
                newHandlers.add(originHandler);
            }
        }
        requestMappingHandlerAdapter.setReturnValueHandlers(newHandlers);
    }
}

自定义 ReturnValueConfig 实现 InitializingBean 接口,afterPropertiesSet 方法会被自动调用,在该方法中,我们将 RequestMappingHandlerAdapter 中已经配置好的 HandlerMethodReturnValueHandler 拎出来挨个检查,如果类型是 RequestResponseBodyMethodProcessor,则重新构建,用我们自定义的 MyHandlerMethodReturnValueHandler 代替它,最后给 requestMappingHandlerAdapter 重新设置 HandlerMethodReturnValueHandler 即可。

最后再提供一个测试接口:

@RestController
public class UserController {
    @GetMapping("/user")
    public User getUserByUsername(String username) {
        User user = new User();
        user.setUsername(username);
        user.setAddress("www.javaboy.org");
        return user;
    }
}
public class User {
    private String username;
    private String address;
    //省略其他
}

配置完成后,就可以启动项目啦。

项目启动成功后,访问 /user 接口,如下:

Spring Boot 中如何统一 API 接口响应格式?

 

完美。

4.小结

其实统一 API 接口响应格式办法很多,可以参考松哥之前分享的 如何优雅的实现 Spring Boot 接口参数加密解密?,也可以使用本文中的方案,甚至也可以自定义过滤器实现。

本文的内容稍微有点多,不知道大家有没有发现松哥最近发了很多 SpringMVC 源码相关的东西,没错,本文其实是松哥 SpringMVC 源码解析的一部分,为了源码解析不那么枯燥,所以强行加了一个案例进来,祝小伙伴们学习愉快~



Tags:API 接口   点击:()  评论:()
声明:本站部分内容及图片来自互联网,转载是出于传递更多信息之目的,内容观点仅代表作者本人,如有任何标注错误或版权侵犯请与我们联系(Email:2595517585@qq.com),我们将及时更正、删除,谢谢。
▌相关推荐
今天又要给大家介绍一个 Spring Boot 中的组件 --HandlerMethodReturnValueHandler。在前面的文章中(如何优雅的实现 Spring Boot 接口参数加密解密?),松哥已经和大家介绍过如何...【详细内容】
2021-03-24  Tags: API 接口  点击:(297)  评论:(0)  加入收藏
使用了注解的方式进行对接口防刷的功能,非常高大上,本文章仅供参考 一,技术要点:springboot的基本知识,redis基本操作,...【详细内容】
2019-12-25  Tags: API 接口  点击:(81)  评论:(0)  加入收藏
前言作为一个以前后端分离为模式开发小组,我们每隔一段时间都进行这样一个场景:前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试...【详细内容】
2019-12-25  Tags: API 接口  点击:(129)  评论:(0)  加入收藏
前言在移动互联网,分布式、微服务盛行的今天,现在项目绝大部分都采用的微服务框架,前后端分离方式,(题外话:前后端的工作职责越来越明确,现在的前端都称之为大前端,技术栈以及生态圈...【详细内容】
2019-11-26  Tags: API 接口  点击:(113)  评论:(0)  加入收藏
协议httphttps(使用HTTPS协议,以确保交互数据的传输安全)域名专门的api应用使用独立域名 https://api.example.com简单的可使用api前缀区分 https://www.example.com/api版本...【详细内容】
2019-09-09  Tags: API 接口  点击:(213)  评论:(0)  加入收藏
获取访客信息 API 接口在网上已经很多且大都封装成了 API 供别人调用。支持前台跨域请求,以GET方式提交即可。获取访客信息 API 接口可以查询网站访客的详细信息,你可以选择调...【详细内容】
2019-08-07  Tags: API 接口  点击:(312)  评论:(0)  加入收藏
▌简易百科推荐
近日只是为了想尽办法为 Flask 实现 Swagger UI 文档功能,基本上要让 Flask 配合 Flasgger, 所以写了篇 Flask 应用集成 Swagger UI 。然而不断的 Google 过程中偶然间发现了...【详细内容】
2021-12-23  Python阿杰    Tags:FastAPI   点击:(6)  评论:(0)  加入收藏
文章目录1、Quartz1.1 引入依赖<dependency> <groupId>org.quartz-scheduler</groupId> <artifactId>quartz</artifactId> <version>2.3.2</version></dependency>...【详细内容】
2021-12-22  java老人头    Tags:框架   点击:(11)  评论:(0)  加入收藏
今天来梳理下 Spring 的整体脉络啦,为后面的文章做个铺垫~后面几篇文章应该会讲讲这些内容啦 Spring AOP 插件 (了好久都忘了 ) 分享下 4ye 在项目中利用 AOP + MybatisPlus 对...【详细内容】
2021-12-07  Java4ye    Tags:Spring   点击:(14)  评论:(0)  加入收藏
&emsp;前面通过入门案例介绍,我们发现在SpringSecurity中如果我们没有使用自定义的登录界面,那么SpringSecurity会给我们提供一个系统登录界面。但真实项目中我们一般都会使用...【详细内容】
2021-12-06  波哥带你学Java    Tags:SpringSecurity   点击:(18)  评论:(0)  加入收藏
React 简介 React 基本使用<div id="test"></div><script type="text/javascript" src="../js/react.development.js"></script><script type="text/javascript" src="../js...【详细内容】
2021-11-30  清闲的帆船先生    Tags:框架   点击:(19)  评论:(0)  加入收藏
流水线(Pipeline)是把一个重复的过程分解为若干个子过程,使每个子过程与其他子过程并行进行的技术。本文主要介绍了诞生于云原生时代的流水线框架 Argo。 什么是流水线?在计算机...【详细内容】
2021-11-30  叼着猫的鱼    Tags:框架   点击:(21)  评论:(0)  加入收藏
TKinterThinter 是标准的python包,你可以在linx,macos,windows上使用它,你不需要安装它,因为它是python自带的扩展包。 它采用TCL的控制接口,你可以非常方便地写出图形界面,如...【详细内容】
2021-11-30    梦回故里归来  Tags:框架   点击:(26)  评论:(0)  加入收藏
前言项目中的配置文件会有密码的存在,例如数据库的密码、邮箱的密码、FTP的密码等。配置的密码以明文的方式暴露,并不是一种安全的方式,特别是大型项目的生产环境中,因为配置文...【详细内容】
2021-11-17  充满元气的java爱好者  博客园  Tags:SpringBoot   点击:(25)  评论:(0)  加入收藏
一、搭建环境1、创建数据库表和表结构create table account(id INT identity(1,1) primary key,name varchar(20),[money] DECIMAL2、创建maven的工程SSM,在pom.xml文件引入...【详细内容】
2021-11-11  AT小白在线中  搜狐号  Tags:开发框架   点击:(29)  评论:(0)  加入收藏
SpringBoot开发的物联网通信平台系统项目功能模块 功能 说明 MQTT 1.SSL支持 2.集群化部署时暂不支持retain&will类型消 UDP ...【详细内容】
2021-11-05  小程序建站    Tags:SpringBoot   点击:(55)  评论:(0)  加入收藏
最新更新
栏目热门
栏目头条