Spring MVC 切面 ResponseBodyAdvice 对响应/返回值增强、API接口数据统一格式返回

蚩尤后裔-汪茂雄

已于 2023-11-12 12:34:23 修改

阅读量7.5w

点赞数 32

分类专栏： Spring Framework 文章标签： java java-ee

于 2018-07-15 16:48:13 首次发布

本文链接：https://blog.csdn.net/wangmx1993328/article/details/81054474

版权

Spring Framework 专栏收录该内容

22 篇文章 8 订阅

订阅专栏

Java 设计 API 接口，实现统一格式返回数据

ResponseBodyAdvice 对响应/返回值增强

ResponseBodyAdvice 接口概述

ResponseBodyAdvice 快速使用

ResponseBodyAdvice 注意事项

Java 设计 API 接口，实现统一格式返回数据

1、前端和后端进行交互，前端按照约定请求 URL 路径，并传入相关参数，后端服务器接收请求，进行业务处理，返回数据给前端。

2、后端服务器以什么格式将数据返回给前端更合适呢？其实可以 F12 查看一下网上别人的格式进行参考，比如如下这种：

3、可以发现一般有：code：状态码，message：消息，total：分页时，表示数据总数，page：分页时，表示当前的页码，size：分页时，表示每页显示的数据条数。

CODE 状态码：可以参考 HTTP 响应状态码。

1、如果上面的区间不够，可以自定义设计成 4 位数，比如：

#1000～1999 区间表示参数错误
#2000～2999 区间表示用户错误
#3000～3999 区间表示接口异常

2、这样开发人员在得到返回值后，根据状态码就可以知道大概什么错误，再根据message相关的信息描述，可以快速定位。

3、实现源码如下：

ResultCode.java ：使用枚举封装常用的状态码与消息

ResultData.java : 封装返回的数据对象

ResultAPI.java ：控制层方法演示封装返回数据

ResponseBodyAdvice 对响应/返回值增强

ResponseBodyAdvice 接口概述

1、ResponseBodyAdvice 接口允许在执行 @ResponseBody 或 ResponseEntity 控制器方法之后，但在使用 HttpMessageConverter 写入响应体之前自定义响应，进行功能增强。通常用于加密，签名，统一数据格式等。

2、ResponseBodyAdvice 接口一共有两个方法：

public interface ResponseBodyAdvice<T> {
    /**
    * 1、选择是否执行 beforeBodyWrite 方法，返回 true 执行，false 不执行.
    * 2、通过 supports 方法，可以选择对哪些类或方法的 Response 进行处理，其余的
则不处理。
    * @param returnType：返回类型
    * @param converterType：转换器
    * @return ：返回 true 则下面的 beforeBodyWrite  执行，否则不执行
    * /
	boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType);
 
    /**
    * 对 Response 处理的具体执行方法
    * @param body：响应对象(response)中的响应体
    * @param returnType：控制器方法的返回类型
    * @param selectedContentType：通过内容协商选择的内容类型
    * @param selectedConverterType：选择写入响应的转换器类型
    * @param request：当前请求
    * @param response：当前响应
    * @return ：返回传入的主体或修改过的(可能是新的)主体
   * /
	@Nullable
	T beforeBodyWrite(@Nullable T body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response);
 
}

ResponseBodyAdvice 快速使用

1、使用方式：自定义类实现 ResponseBodyAdvice 接口，然后在类上标记 @ControllerAdvice 或@RestControllerAdvice 注解即可自动识别并进行功能增强。

2、下面以对返回数据封装统一格式为例进行演示（注意仅对返回值为 ResponseEntity 或者是有@ResponseBody 注解的控制器方法进行拦截，@RestController 相当于是类中的所有方法上都加了 @ResponseBody）。

3、注意如果控制层目标方法往外抛出了异常，则不再进入 ResponseBodyAdvice

/**
 * 对返回数据增强，封装成统一格式
 * 1、ResponseBodyAdvice 需要绑定到 {@link @RestControllerAdvice} 或者 {@link @ControllerAdvice} 才能生效。
 * 2、注意仅对返回值为 ResponseEntity 或者是有 @ResponseBody 注解的控制器方法进行拦截，
 * * @RestController 标记的类，相当于是类中的所有方法上都加了 @ResponseBody。
 * 3、@RestControllerAdvice 默认是针对所有的控制器，但也可以指定某个包，及其子包都会进行拦截。
 *
 * @author wangMaoXiong
 * @version 1.0
 * @date 2022/4/16 14:31
 */
@RestControllerAdvice(basePackages = "com.wmx")
public class CommonResultAdvice implements ResponseBodyAdvice<Object> {
    /**
     * 1、当且仅当本方法返回 true 时，下面的 beforeBodyWrite 方法才会执行。
     * 2、可以直接返回 true，此时全部经过下面的 beforeBodyWrite 方法。如下演示的是自己包下面的控制器方法返回时才进行增强。
     *
     * @param returnType：返回类型
     * @param converterType：转换器
     * @return
     */
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        /**
         * Class<?> getDeclaringClass() ：返回声明基础方法或构造函数的类，比如 com.wmx.wmxredis.properties.PropertiesController
         */
        return returnType.getDeclaringClass().getName().contains("com.wmx");
    }
    /**
     * 对返回的数据统一组装成 {@link ResultData} 格式
     *
     * @param body：响应对象(response)中的响应体
     * @param returnType：控制器方法的返回类型
     * @param selectedContentType：通过内容协商选择的内容类型
     * @param selectedConverterType：选择写入响应的转换器类型
     * @param request：当前请求
     * @param response：当前响应
     * @return ：返回传入的主体或修改过的(可能是新的)主体
     */
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        return body instanceof ResultData ? body : new ResultData(ResultCode.SUCCESS, body);
    }
}

/CommonResultAdvice.java· 汪少棠/wmx-redis - Gitee.com

/PropertiesController.java · 汪少棠/wmx-redis - Gitee.com

/ResultData.java · 汪少棠/wmx-redis - Gitee.com

ResponseBodyAdvice 注意事项

1、ResponseBodyAdvice 切面执行与否要看最终返回的响应：当且仅当返回值为 ResponseEntity 的方法，或者是有@ResponseBody 注解的方法才进行拦截。@RestController 相当于是类中的所有方法上都加了 @ResponseBody。

2、假如目标控制层方法往外抛出了异常，此时如果没有使用 @ControllerAdvice + @ExceptionHandler 或者 @RestControllerAdvice + @ExceptionHandler 进行全局统一异常处理，则不再继续执行 ResponseBodyAdvice 切面，因为它已经不满足第一点的条件。

3、假如目标控制层方法往外抛出了异常，并使用 @ControllerAdvice + @ExceptionHandler 进行全局统一异常处理，此时如果异常处理方法没有继续往外抛异常，且捕获方法使用了 @ResponseBody 注解或者返回的是 ResponseEntity ，则仍然会继续执行 ResponseBodyAdvice 切面，否则比如做页面跳转等操作时则不再继续执行。

4、假如目标控制层方法往外抛出了异常，并使用 @RestControllerAdvice + @ExceptionHandler 进行全局统一异常处理，只要捕获方法没有往外继续抛异常，则仍然会继续执行 ResponseBodyAdvice 切面，因为 @RestControllerAdvice 注解包含了 @ResponseBody 注解。