目录
背景
越来越多的项目开始基于前后端分离的模式进行开发，这对后端接口的报文格式便有了一定的要求。通常，我们会采用 JSON 格式作为前后端交换数据格式，从而减少沟通成本等。
这篇文章，就带大家了解一下基于 SpringBoot 框架来封装返回报文以及统一异常处理。
报文基本格式
一般报文格式通常会包含状态码、状态描述（或错误提示信息）、业务数据等信息。 在此基础上，不同的架构师、项目搭建者可能会有所调整。 但从整体上来说，基本上都是大同小异。
在 SpringBoot 项目中，通常接口返回的报文中至少包含三个属性：
示例报文如下：
{ "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 的实现，如果你的项目中采用了其他的技术栈，则可考虑对应的处理方式。 同时，日常中很多类似的功能都可以统一进行处理，避免大量无效的硬编码。
评论