关于java:Spring-Boot-中如何统一-API-接口响应格式

明天又要给大家介绍一个 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 有很多默认的实现类，咱们来看下：

接下来咱们来把这些实现类的作用捋一捋：

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，所以这块的逻辑是这样：

如果 redirectModelScenario 为 true，即处理器返回的是一个重定向视图，那么应用 redirectModel。如果 redirectModelScenario 为 false，即处理器返回的不是一个重定向视图，那么应用 defaultModel。
如果 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 接口数据包装

假如我有这样一个需要：我想在原始的返回数据里面再包裹一层，举个简略例子，原本接口是上面这样：

@RestControllerpublic 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 的状况。

咱们来略微看下：

@Overridepublic boolean supportsReturnType(MethodParameter returnType) {    return (AnnotatedElementUtils.hasAnnotation(returnType.getContainingClass(), ResponseBody.class) ||            returnType.hasMethodAnnotation(ResponseBody.class));}@Overridepublic 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 进行批改，如下：

@Configurationpublic 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 即可。

最初再提供一个测试接口：

@RestControllerpublic 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 接口，如下：

完满。

4.小结

其实对立 API 接口响应格局方法很多，能够参考松哥之前分享的如何优雅的实现 Spring Boot 接口参数加密解密？，也能够应用本文中的计划，甚至也能够自定义过滤器实现。

本文的内容略微有点多，不晓得大家有没有发现松哥最近发了很多 SpringMVC 源码相干的货色，没错，本文其实是松哥 SpringMVC 源码解析的一部分，为了源码解析不那么干燥，所以强行加了一个案例进来，祝小伙伴们学习欢快～