写点什么

SpringBoot 如何优雅地进行响应数据封装、异常处理?

作者:程序员小毕
  • 2022 年 8 月 03 日
  • 本文字数:4367 字

    阅读完需:约 14 分钟

SpringBoot如何优雅地进行响应数据封装、异常处理?

背景

越来越多的项目开始基于前后端分离的模式进行开发,这对后端接口的报文格式便有了一定的要求。通常,我们会采用 JSON 格式作为前后端交换数据格式,从而减少沟通成本等。

这篇文章,就带大家了解一下基于 SpringBoot 框架来封装返回报文以及统一异常处理。

报文基本格式

一般报文格式通常会包含状态码、状态描述(或错误提示信息)、业务数据等信息。在此基础上,不同的架构师、项目搭建者可能会有所调整。但从整体上来说,基本上都是大同小异。

在 SpringBoot 项目中,通常接口返回的报文中至少包含三个属性:

  • code:请求接口的返回码,成功或者异常等返回编码,例如定义请求成功。

  • message:请求接口的描述,也就是对返回编码的描述。

  • data:请求接口成功,返回的业务数据。

示例报文如下:

{  "code":200,  "message":"SUCCESS",  "data":{    "info":"测试成功"  }}
复制代码

在上述报文格式中,不同的设计者是会有一些分歧的,特别是 code 值的定义。如果完全基于 RESTful API 设计的话,code 字段可能就不需要存在了,而是通过 HTTP 协议中提供的 GET、POST、PUT、DELETE 操作等来完成资源的访问。

但在实践中,不论是出于目前国内大多数程序员的习惯,还是受限于 HTTP 协议提供的操作方法的局限性,很少完全遵照 RESTful API 方式进行设计。通常都是通过自定义 Code 值的形式来赋予它业务意义或业务错误编码。

虽然可以不用完全遵守 RESTful API 风格来定义 Code,在 Code 值的自定义中,也存在两种形式:遵循 HTTP 状态码和自主定义。

像上面的示例,用 200 表示返回成功,这就是遵循 HTTP 响应状态码的形式来返回,比如还有其他的 400、401、404、500 等。当然,还有完全自主定义的,比如用 0 表示成功,1 表示失败,然后再跟进通用编码、业务分类编码等进行定义。

在此,笔者暂不评论每种形式的好坏,只列举了常规的几种形式,大家了解对应的情况,做到心中有数,有所选择即可。

响应参数封装实践

创建一个 SpringBoot 项目,并引入 Lombok 依赖(精简代码),对应的核心依赖如下:

    <dependencies>        <dependency>            <groupId>org.springframework.boot</groupId>            <artifactId>spring-boot-starter-web</artifactId>        </dependency>        <dependency>            <groupId>org.projectlombok</groupId>            <artifactId>lombok</artifactId>        </dependency>    </dependencies>
复制代码

创建枚举类,用于定义返回的错误码:

@Getter@AllArgsConstructorpublic enum ResponseCodeEnums {
 SUCCESS(200, "success"), FAIL(500, "failed"),
 HTTP_STATUS_200(200, "ok"), HTTP_STATUS_400(400, "request error"), HTTP_STATUS_401(401, "no authentication"), HTTP_STATUS_403(403, "no authorities"), HTTP_STATUS_500(500, "server error");
 private final int code;
 private final String message;}
复制代码

这里只定义了一些通用的、基于的 HTTP 响应状态码,业务相关的编码可根据业务需求进行定义。

定义统一返回结果实体类:

@Datapublic class ResponseInfo<T> {
 /**  * 状态码  */ protected int code;
 /**  * 响应信息  */ protected String message;
 /**  * 返回数据  */ private T data;
 public static <T> ResponseInfo<T> success() {  return new ResponseInfo<>(); }
 public static <T> ResponseInfo<T> success(T data) {  return new ResponseInfo<>(data); }
 public static <T> ResponseInfo<T> fail(String message) {  return new ResponseInfo<>(ResponseCodeEnums.FAIL.getCode(), message); }
 public ResponseInfo() {  this.code = ResponseCodeEnums.SUCCESS.getCode();  this.message = ResponseCodeEnums.SUCCESS.getMessage(); }
 public ResponseInfo(ResponseCodeEnums statusEnums) {  this.code = statusEnums.getCode();  this.message = statusEnums.getMessage(); }
 /**  * 若没有数据返回,可以人为指定状态码和提示信息  */ public ResponseInfo(int code, String msg) {  this.code = code;  this.message = msg; }
 /**  * 有数据返回时,状态码为200,默认提示信息为“操作成功!”  */ public ResponseInfo(T data) {  this.data = data;  this.code = ResponseCodeEnums.SUCCESS.getCode();  this.message = ResponseCodeEnums.SUCCESS.getMessage(); }
 /**  * 有数据返回,状态码为 200,人为指定提示信息  */ public ResponseInfo(T data, String msg) {  this.data = data;  this.code = ResponseCodeEnums.SUCCESS.getCode();  this.message = msg; }}
复制代码

在 ResponseInfo 中运用了泛型和公共方法、构造方法的封装,方便在业务中使用。示例中只提供了部分方法的封装,根据自身业务场景和需要可进一步封装。

统一报文封装在接口中的使用:

@Slf4j@RestControllerpublic class TestController {
 @RequestMapping("/calc") public ResponseInfo<String> calc(Integer id) {  try {   // 模拟异常业务代码   int num = 1 / id;   log.info("计算结果num={}", num);   return ResponseInfo.success();  } catch (Exception e) {   return ResponseInfo.fail("系统异常,请联系管理员!");  } }}
复制代码

在浏览器中访问:http://localhost:8080/calc,返回结果如下:

{    "code": 500,    "message": "系统异常,请联系管理员!",    "data": null}
复制代码

这是因为没传递 id 参数,导致业务抛异常,走异常报文返回。

在浏览器中访问:http://localhost:8080/calc?id=1,返回结果如下:

{    "code": 200,    "message": "success",    "data": null}
复制代码

正常返回结果。

统一异常处理

在上述实例中,我们通过 try...catch 的形式捕获异常,并进行处理。在 SpringBoot 中,我们可以通过 RestControllerAdvice 注解来定义全局异常处理,这样就无需每处都 try...catch 了。

@Slf4j@RestControllerAdvicepublic class ExceptionHandlerAdvice {
 /**  * 参数格式异常处理  */ @ExceptionHandler({IllegalArgumentException.class}) @ResponseStatus(HttpStatus.BAD_REQUEST) public ResponseInfo<String> badRequestException(IllegalArgumentException ex) {  log.error("参数格式不合法:{}", ex.getMessage());  return new ResponseInfo<>(HttpStatus.BAD_REQUEST.value() + "", "参数格式不符!"); }
 /**  * 权限不足异常处理  */ @ExceptionHandler({AccessDeniedException.class}) @ResponseStatus(HttpStatus.FORBIDDEN) public ResponseInfo<String> badRequestException(AccessDeniedException ex) {  return new ResponseInfo<>(HttpStatus.FORBIDDEN.value() + "", ex.getMessage()); }
 /**  * 参数缺失异常处理  */ @ExceptionHandler({MissingServletRequestParameterException.class}) @ResponseStatus(HttpStatus.BAD_REQUEST) public ResponseInfo<String> badRequestException(Exception ex) {  return new ResponseInfo<>(HttpStatus.BAD_REQUEST.value() + "", "缺少必填参数!"); }
 /**  * 空指针异常  */ @ExceptionHandler(NullPointerException.class) @ResponseStatus(value = HttpStatus.INTERNAL_SERVER_ERROR) public ResponseInfo<String> handleTypeMismatchException(NullPointerException ex) {  log.error("空指针异常,{}", ex.getMessage());  return ResponseInfo.fail("空指针异常"); }
 @ExceptionHandler(Exception.class) @ResponseStatus(value = HttpStatus.INTERNAL_SERVER_ERROR) public ResponseInfo<String> handleUnexpectedServer(Exception ex) {  log.error("系统异常:", ex);  return ResponseInfo.fail("系统发生异常,请联系管理员"); }
 /**  * 系统异常处理  */ @ExceptionHandler(Throwable.class) @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR) public ResponseInfo<String> exception(Throwable throwable) {  log.error("系统异常", throwable);  return new ResponseInfo<>(HttpStatus.INTERNAL_SERVER_ERROR.value() + "系统异常,请联系管理员!"); }}
复制代码

在上述方法中,对一些常见的异常进行了统一处理。通常情况下,根据业务需要还会定义业务异常,并对业务异常进行处理,大家可以根据自己项目中异常的使用情况进行拓展。

关于 @RestControllerAdvice 的几点说明:

  • @RestControllerAdvice 注解包含了 @Component 注解,会把被注解的类作为组件交给 Spring 来管理。

  • @RestControllerAdvice 注解包含了 @ResponseBody 注解,异常处理完之后给调用方输出一个 JSON 格式的封装数据。

  • @RestControllerAdvice 注解有一个 basePackages 属性,该属性用来拦截哪个包中的异常信息,一般不指定,拦截项目工程中的所有异常。

  • 在方法上通过 @ExceptionHandler 注解来指定具体的异常,在方法中处理该异常信息,最后将结果通过统一的 JSON 结构体返回给调用者。

重新定义一个接口:

 @RequestMapping("/calc1") public ResponseInfo<String> calc1(Integer id) {  // 模拟异常业务代码  int num = 1 / id;  log.info("计算结果num={}", num);  return ResponseInfo.success(); }
复制代码

在请求的时候,不传递 id 值,即在浏览器中访问:

{    "code": 500,    "message": "空指针异常",    "data": null}
复制代码

可以看到统一异常处理对空指针异常进行了拦截处理,并返回了 ExceptionHandlerAdvice 中定义的统一报文格式。

小结

在使用 SpringBoot 或其他项目中,统一的报文格式和统一的异常处理都是必须的。本篇文章介绍了基于 SpringBoot 的实现,如果你的项目中采用了其他的技术栈,则可考虑对应的处理方式。同时,日常中很多类似的功能都可以统一进行处理,避免大量无效的硬编码。

原文链接:https://mp.weixin.qq.com/s/tgpSpAKSA3kWsu7Xox-wNQ

如果感觉本文对你有帮助,点赞关注支持一下,想要了解更多 Java 后端,大数据,算法领域最新资讯可以关注我公众号【架构师老毕】私信 666 还可获取更多 Java 后端,大数据,算法 PDF+大厂最新面试题整理+视频精讲

用户头像

领取资料添加小助理vx:bjmsb2020 2020.12.19 加入

Java领域;架构知识;面试心得;互联网行业最新资讯

评论

发布
暂无评论
SpringBoot如何优雅地进行响应数据封装、异常处理?_Java_程序员小毕_InfoQ写作社区