详解SpringBoot 统一后端返回格式的方法

目录
  • 为什么要对SpringBoot返回统一的标准格式
  • 定义返回标准格式
    • 定义返回对象
    • 定义状态码
    • 统一返回格式
    • 高级实现方式
    • 接口异常问题
  • SpringBoot为什么需要全局异常处理器
    • 如何实现全局异常处理器
    • 体验效果
    • 全局异常接入返回的标准格式

首先我们来看看为什么要返回统一的标准格式?

为什么要对SpringBoot返回统一的标准格式

在默认情况下,SpringBoot的返回格式常见的有三种:

第一种:返回 String

@GetMapping("/hello")
public String getStr(){
  return "hello,javadaily";
}

此时调用接口获取到的返回值是这样:

hello,javadaily

第二种:返回自定义对象

@GetMapping("/aniaml")
public Aniaml getAniaml(){
  Aniaml aniaml = new Aniaml(1,"pig");
  return aniaml;
}

此时调用接口获取到的返回值是这样:

{
  "id": 1,
  "name": "pig"
}

第三种:接口异常

@GetMapping("/error")
public int error(){
    int i = 9/0;
    return i;
}

此时调用接口获取到的返回值是这样:

{
  "timestamp": "2021-07-08T08:05:15.423+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/wrong"
}

基于以上种种情况,如果你和前端开发人员联调接口她们就会很懵逼,由于我们没有给他一个统一的格式,前端人员不知道如何处理返回值。

还有甚者,有的同学比如小张喜欢对结果进行封装,他使用了Result对象,小王也喜欢对结果进行包装,但是他却使用的是Response对象,当出现这种情况时我相信前端人员一定会抓狂的。

所以我们项目中是需要定义一个统一的标准返回格式的。

定义返回标准格式

一个标准的返回格式至少包含3部分:

  1. status 状态值:由后端统一定义各种返回结果的状态码
  2. message 描述:本次接口调用的结果描述
  3. data 数据:本次返回的数据。
{
  "status":"100",
  "message":"操作成功",
  "data":"hello,javadaily"
}

当然也可以按需加入其他扩展值,比如我们就在返回对象中添加了接口调用时间

timestamp: 接口调用时间

定义返回对象

@Data
public class ResultData<T> {
  /** 结果状态 ,具体状态码参见ResultData.java*/
  private int status;
  private String message;
  private T data;
  private long timestamp ;
  public ResultData (){
    this.timestamp = System.currentTimeMillis();
  }
  public static <T> ResultData<T> success(T data) {
    ResultData<T> resultData = new ResultData<>();
    resultData.setStatus(ReturnCode.RC100.getCode());
    resultData.setMessage(ReturnCode.RC100.getMessage());
    resultData.setData(data);
    return resultData;
  }
  public static <T> ResultData<T> fail(int code, String message) {
    ResultData<T> resultData = new ResultData<>();
    resultData.setStatus(code);
    resultData.setMessage(message);
    return resultData;
  }
}

定义状态码

public enum ReturnCode {
    /**操作成功**/
    RC100(100,"操作成功"),
    /**操作失败**/
    RC999(999,"操作失败"),
    /**服务限流**/
    RC200(200,"服务开启限流保护,请稍后再试!"),
    /**服务降级**/
    RC201(201,"服务开启降级保护,请稍后再试!"),
    /**热点参数限流**/
    RC202(202,"热点参数限流,请稍后再试!"),
    /**系统规则不满足**/
    RC203(203,"系统规则不满足要求,请稍后再试!"),
    /**授权规则不通过**/
    RC204(204,"授权规则不通过,请稍后再试!"),
    /**access_denied**/
    RC403(403,"无访问权限,请联系管理员授予权限"),
    /**access_denied**/
    RC401(401,"匿名用户访问无权限资源时的异常"),
    /**服务异常**/
    RC500(500,"系统异常,请稍后重试"),
    INVALID_TOKEN(2001,"访问令牌不合法"),
    ACCESS_DENIED(2003,"没有权限访问该资源"),
    CLIENT_AUTHENTICATION_FAILED(1001,"客户端认证失败"),
    USERNAME_OR_PASSWORD_ERROR(1002,"用户名或密码错误"),
    UNSUPPORTED_GRANT_TYPE(1003, "不支持的认证模式");
    /**自定义状态码**/
    private final int code;
    /**自定义描述**/
    private final String message;
    ReturnCode(int code, String message){
        this.code = code;
        this.message = message;
    }
    public int getCode() {
        return code;
    }
    public String getMessage() {
        return message;
    }
}

统一返回格式

@GetMapping("/hello")
public ResultData<String> getStr(){
 return ResultData.success("hello,javadaily");
}

此时调用接口获取到的返回值是这样:

{
  "status": 100,
  "message": "hello,javadaily",
  "data": null,
  "timestamp": 1625736481648,
  "httpStatus": 0
}

这样确实已经实现了我们想要的结果,我在很多项目中看到的都是这种写法,在Controller层通过ResultData.success()对返回结果进行包装后返回给前端。

看到这里我们不妨停下来想想,这样做有什么弊端呢?

最大的弊端就是我们后面每写一个接口都需要调用ResultData.success()这行代码对结果进行包装,重复劳动,浪费体力;

而且还很容易被其他老鸟给嘲笑。

 

所以呢我们需要对代码进行优化,目标就是不要每个接口都手工制定ResultData返回值。

高级实现方式

要优化这段代码很简单,我们只需要借助SpringBoot提供的ResponseBodyAdvice即可。

“ResponseBodyAdvice的作用:拦截Controller方法的返回值,统一处理返回值/响应体,一般用来统一返回格式,加解密,签名等等。

先来看下ResponseBodyAdvice的源码:

public interface ResponseBodyAdvice<T> {
  /**
  * 是否支持advice功能
  * true 支持,false 不支持
  */
    boolean supports(MethodParameter var1, Class<? extends HttpMessageConverter<?>> var2);

   /**
  * 对返回的数据进行处理
  */
    @Nullable
    T beforeBodyWrite(@Nullable T var1, MethodParameter var2, MediaType var3, Class<? extends HttpMessageConverter<?>> var4, ServerHttpRequest var5, ServerHttpResponse var6);
}

我们只需要编写一个具体实现类即可

/**
 * @author jam
 * @date 2021/7/8 10:10 上午
 */
@RestControllerAdvice
public class ResponseAdvice implements ResponseBodyAdvice<Object> {
    @Autowired
    private ObjectMapper objectMapper;

    @Override
    public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
        return true;
    }
    @SneakyThrows
    @Override
    public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
        if(o instanceof String){
            return objectMapper.writeValueAsString(ResultData.success(o));
        }
        return ResultData.success(o);
    }
}

需要注意两个地方:

@RestControllerAdvice注解

@RestControllerAdvice@RestController注解的增强,可以实现三个方面的功能:

  1. 全局异常处理
  2. 全局数据绑定
  3. 全局数据预处理

String类型判断

if(o instanceof String){
  return objectMapper.writeValueAsString(ResultData.success(o));
} 

这段代码一定要加,如果Controller直接返回String的话,SpringBoot是直接返回,故我们需要手动转换成json。

经过上面的处理我们就再也不需要通过ResultData.success()来进行转换了,直接返回原始数据格式,SpringBoot自动帮我们实现包装类的封装。

@GetMapping("/hello")
public String getStr(){
    return "hello,javadaily";
}

此时我们调用接口返回的数据结果为:

@GetMapping("/hello")
public String getStr(){
  return "hello,javadaily";
}

是不是感觉很完美,别急,还有个问题在等着你呢。

接口异常问题

此时有个问题,由于我们没对Controller的异常进行处理,当我们调用的方法一旦出现异常,就会出现问题,比如下面这个接口

@GetMapping("/wrong")
public int error(){
    int i = 9/0;
    return i;
}

返回的结果为:

这显然不是我们想要的结果,接口都报错了还返回操作成功的响应码,前端看了会打人的。

别急,接下来我们进入第二个议题,如何优雅的处理全局异常。

SpringBoot为什么需要全局异常处理器

不用手写try...catch,由全局异常处理器统一捕获

使用全局异常处理器最大的便利就是程序员在写代码时不再需要手写try...catch了,前面我们讲过,默认情况下SpringBoot出现异常时返回的结果是这样:

{
  "timestamp": "2021-07-08T08:05:15.423+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/wrong"
}

这种数据格式返回给前端,前端是看不懂的,所以这时候我们一般通过try...catch来处理异常

@GetMapping("/wrong")
public int error(){
    int i;
    try{
        i = 9/0;
    }catch (Exception e){
        log.error("error:{}",e);
        i = 0;
    }
    return i;
}

我们追求的目标肯定是不需要再手动写try...catch了,而是希望由全局异常处理器处理。

对于自定义异常,只能通过全局异常处理器来处理

@GetMapping("error1")
public void empty(){
 throw  new RuntimeException("自定义异常");
}

当我们引入Validator参数校验器的时候,参数校验不通过会抛出异常,此时是无法用try...catch捕获的,只能使用全局异常处理器。

“SpringBoot集成参数校验请参考这篇文章SpringBoot开发秘籍 - 集成参数校验及高阶技巧

如何实现全局异常处理器

@Slf4j
@RestControllerAdvice
public class RestExceptionHandler {
    /**
     * 默认全局异常处理。
     * @param e the e
     * @return ResultData
     */
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ResultData<String> exception(Exception e) {
        log.error("全局异常信息 ex={}", e.getMessage(), e);
        return ResultData.fail(ReturnCode.RC500.getCode(),e.getMessage());
    }

}

有三个细节需要说明一下:

  1. @RestControllerAdvice,RestController的增强类,可用于实现全局异常处理器
  2. @ExceptionHandler,统一处理某一类异常,从而减少代码重复率和复杂度,比如要获取自定义异常可以@ExceptionHandler(BusinessException.class)
  3. @ResponseStatus指定客户端收到的http状态码

体验效果

这时候我们调用如下接口:

@GetMapping("error1")
public void empty(){
    throw  new RuntimeException("自定义异常");
}

返回的结果如下:

{
  "status": 500,
  "message": "自定义异常",
  "data": null,
  "timestamp": 1625795902556
}

基本满足我们的需求了。

但是当我们同时启用统一标准格式封装功能ResponseAdviceRestExceptionHandler全局异常处理器时又出现了新的问题:

{
  "status": 100,
  "message": "操作成功",
  "data": {
    "status": 500,
    "message": "自定义异常",
    "data": null,
    "timestamp": 1625796167986
  },
  "timestamp": 1625796168008
}

此时返回的结果是这样,统一格式增强功能会给返回的异常结果再次封装,所以接下来我们需要解决这个问题。

全局异常接入返回的标准格式

要让全局异常接入标准格式很简单,因为全局异常处理器已经帮我们封装好了标准格式,我们只需要直接返回给客户端即可。

@SneakyThrows
@Override
public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
  if(o instanceof String){
    return objectMapper.writeValueAsString(ResultData.success(o));
  }
  if(o instanceof ResultData){
    return o;
  }
  return ResultData.success(o);
}

关键代码:

if(o instanceof ResultData){
  return o;
}

如果返回的结果是ResultData对象,直接返回即可。

这时候我们再调用上面的错误方法,返回的结果就符合我们的要求了。

{
  "status": 500,
  "message": "自定义异常",
  "data": null,
  "timestamp": 1625796580778
}

好了,今天的文章就到这里了,希望通过这篇文章你能掌握如何在你项目中友好实现统一标准格式到返回并且可以优雅的处理全局异常。

github地址:https://github.com/jianzh5/cloud-blog/

到此这篇关于详解SpringBoot 统一后端返回格式的方法的文章就介绍到这了,更多相关SpringBoot 统一后端返回格式内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • springboot 返回json格式数据时间格式配置方式

    目录 返回json格式数据时间格式配置 返回JSON日期格式问题 返回json格式数据时间格式配置 数据库里面查出来的时间是时间错格式,前段需要处理才能展示相应的格式,自己一个个转的话太麻烦,所以可以在apllication.property加入下面配置就可以 #时间戳统一转换 spring.jackson.date-format=yyyy-MM-dd HH:mm:ss spring.jackson.time-zone=GMT+8 其中time-zone是时区偏移设置,如果不指定的话时间和北京时

  • SpringBoot全局Controller返回值格式统一

    目录 一.返回值格式统一 1.返回值介绍 2.基础类功能 3.基础实现 二.附录说明 一.返回值格式统一 1.返回值介绍 在使用controller对外提供服务的时候,很多时候都需要统一返回值格式,例如 { "status": true, "message": null, "code": "200", "data": { "name": "json", "d

  • 详解SpringBoot如何实现统一后端返回格式

    目录 1.为什么要对SpringBoot返回统一的标准格式 1.1 返回String 1.2 返回自定义对象 1.3 接口异常 2.定义返回对象 3.定义状态码 4.统一返回格式 5.高级实现方式 5.1 ResponseBodyAdvice的源码 5.2 String类型判断 在前后端分离的项目中后端返回的格式一定要友好,不然会对前端的开发人员带来很多的工作量.那么SpringBoot如何做到统一的后端返回格式呢?今天我们一起来看看. 1.为什么要对SpringBoot返回统一的标准格式 在默

  • 关于springboot的接口返回值统一标准格式

    目录 一.目标 二.为什么要对springboot的接口返回值统一标准格式? 第一种格式:response为String 第二种格式:response为Objct 第三种格式:response为void 第四种格式:response为异常 三.定义response的标准格式 四.初级程序员对response代码封装 步骤1:把标准格式转换为代码 步骤2:把状态码存在枚举类里面 步骤3:加一个体验类 五.高级程序员对response代码封装 步骤1:采用ResponseBodyAdvice技术来实

  • 详解SpringBoot如何统一后端返回格式

    目录 为什么要对SpringBoot返回统一的标准格式 第一种:返回 String 第二种:返回自定义对象 第三种:接口异常 定义返回标准格式 高级实现方式 接口异常问题 SpringBoot为什么需要全局异常处理器 体验效果 全局异常接入返回的标准格式 今天我们来聊一聊在基于SpringBoot前后端分离开发模式下,如何友好的返回统一的标准格式以及如何优雅的处理全局异常. 首先我们来看看为什么要返回统一的标准格式? 为什么要对SpringBoot返回统一的标准格式 在默认情况下,SpringB

  • 详解SpringBoot 统一后端返回格式的方法

    目录 为什么要对SpringBoot返回统一的标准格式 定义返回标准格式 定义返回对象 定义状态码 统一返回格式 高级实现方式 接口异常问题 SpringBoot为什么需要全局异常处理器 如何实现全局异常处理器 体验效果 全局异常接入返回的标准格式 首先我们来看看为什么要返回统一的标准格式? 为什么要对SpringBoot返回统一的标准格式 在默认情况下,SpringBoot的返回格式常见的有三种: 第一种:返回 String @GetMapping("/hello") public

  • 详解SpringBoot读取配置文件的N种方法

    我们在项目开发中经常会用到配置信息,例如数据库连接的帐号.密码等,而为了方便维护,我们通常将这些信息放到配置文件中.在需要用到这些配置信息时,可以通过代码获取.下面我们看看Spring中有哪些获取配置信息的方法. PropertiesLoaderUtils读取 通过ClassPathResource加载配置文件资源,结合PropertiesLoaderUtils类读取,源码如下: ClassPathResource resource = new ClassPathResource("applic

  • 一文详解如何根据后端返回的url下载json文件

    目录 需求场景描述 实现思路分析 完整的 demo 示例 总结 需求场景描述 有时候会遇到异步接口会返回一个 url 地址,然后前端需要根据这个 url 地址去下载文件资源的需求场景. 而这个 url 其实是一个静态资源地址,并非一个经过后端接口内部处理的接口地址. 所以当尝试像下面这样使用 a 标签去执行该 url 地址,会发现它是直接预览打开的一个 json 文件(也可能是一个txt,js等文件) <a href=" http://192.168.0.172:8888/file/pac

  • 详解SpringBoot统一响应体解决方案

    前言 最近在优化自己之前基于Spring AOP的统一响应体的实现方案. 什么是统一响应体呢?在目前的前后端分离架构下,后端主要是一个RESTful API的数据接口. 但是HTTP的状态码数量有限,而随着业务的增长,HTTP状态码无法很好地表示业务中遇到的异常情况. 那么可以通过修改响应返回的JSON数据,让其带上一些固有的字段,例如以下这样的 { "code": 10000, "msg": "success", "data"

  • 详解springboot 使用c3p0数据库连接池的方法

    使用springboot开发时,默认使用内置的tomcat数据库连接池,经常碰到这种情况:运行时间一长,数据库连接中断了.所以使用c3p0连接池吧. 引入的maven依赖: <dependency> <groupId>c3p0</groupId> <artifactId>c3p0</artifactId> <version>0.9.1.2</version> </dependency> c3p0的配置信息,写到

  • SpringBoot统一返回格式的方法详解

    目录 前言 1. 直接返回结果 2. 约定返回格式 3. 返回统一格式结果 4. 切片封装统一格式 编写注解 编写ControllerAdvice 见证奇迹的时刻到了 5. 自定义返回格式 场景1:返回成功时code为200 场景2:自定义返回格式 前言 目前很多项目都是前后端分离,前后端会事先约定好返回格式.那么后端如何做,才能优雅的返回统一格式呢,接下来,请大家跟着我,一步步来实现. 1. 直接返回结果 先看一下最基本的例子,直接将结果原封不动返回: @Data @AllArgsConstr

  • 详解SpringBoot定制@ResponseBody注解返回的Json格式

     1.引言 在SpringMVC的使用中,后端与前端的交互一般是使用Json格式进行数据传输,SpringMVC的@ResponseBody注解可以很好的帮助我们进行转换,但是后端返回数据给前端往往都有约定固定的格式,这时候我们在后端返回的时候都要组拼成固定的格式,每次重复的操作非常麻烦. 2.SpringMVC对@ResponseBody的处理 SpringMVC处理@ResponseBody注解声明的Controller是使用默认的.RequestResponseBodyMethodProc

  • 详解SpringBoot中的参数校验(项目实战)

    Java后端发工作中经常会对前端传递过来的参数做一些校验,在业务中还要抛出异常或者不断的返回异常时的校验信息,充满了if-else这种校验代码,在代码中相当冗长.例如说,用户注册时,会校验手机格式的正确性,用户名的长度等等.虽说前端也可以做参数校验,但是为了保证我们API接口的可靠性,以保证最终数据入库的正确性,后端进行参数校验不可忽视. Hibernate Validator 提供了一种统一方便的方式,让我们快速的实现参数校验. Hibernate Validator 使用注解,实现声明式校验

随机推荐