上一篇:Spring Boot 3.x Rest API最佳实践之统一响应结构
在Spring MVC应用中,要对web表示层所抛出的异常进行捕获处理有多种方式,具体的可参考著名国外Spring技术实战网站baeldung上的相关话题。Spring Boot对Spring MVC应用中抛出的异常以及http错误的捕获处理流程做了统一的封装,最终以特定的json
结构响应给前端,而我们要做的只是扩展它对json
结果的包装方式,以我们想要的结构返回即可。
接下来的实践,我们将自定义异常、业务错误码以及错误响应结构三者融合起来,实现定制化的企业级统一异常处理方案。如果觉得对你有帮助,记得点赞收藏,关注小卷,后续更精彩!
定义和抛出自定义异常
自定义一个异常,从RuntimeException
继承,编译期无需处理。先考虑只用msg
来构造。
package com.juan.demo.common.exception;public class BusinessException extends RuntimeException {public BusinessException(String msg) {super(msg);}}
在添加购物车的service方法中模拟抛出,启动服务,测试看响应结果。
...
public class CartServiceImpl implements CartService {@Overridepublic List<CartItemDTO> addCartItem(CartItemDTO addItemDTO) {// 模拟抛出异常if (addItemDTO.getProductId() == 2) {throw new BusinessException("该商品已经下架,无法添加到购物车");}...}
}
测试发现输出的错误结构,包含在数据域data
中,且包含了太多我们不关心的信息。
由于篇幅限制,这里的trace
项内容非常多,这里省略掉。data
域中响应的内容其实是spring boot
框架内部对错误统一处理的结果,只不过在我们之前实现统一响应处理的RestBodyAdvice
中也一并进行了拦截处理。
扩展DefaultErrorAttributes
spring boot
内部对各种异常和http
错误进行了相关捕获和保存,在响应输出到目标控制器,也就是BasicErrorController
前,在DefaultErrorAttributes
进行了错误信息的获取和结构的封装处理,这里,我们可以通过继承DefaultErrorAttributes
类,重写其getErrorAttributes
方法,来改变要响应的错误结构。
package com.juan.demo.common.web.support;import ...@Slf4j
@Component
public class CustomErrorAttributes extends DefaultErrorAttributes {static final String ERR_RESP_KEY = "err_resp";@Overridepublic Map<String, Object> getErrorAttributes(WebRequest webRequest, ErrorAttributeOptions options) {log.info("开始收集和整理错误结构...");Response<?> errResp = buildErrResp(webRequest);return Map.of(ERR_RESP_KEY, errResp);}private Response<?> buildErrResp(WebRequest webRequest) {// 参考了父类中获取抛出的错误对象的代码Throwable error = getError(webRequest);if (error != null) {while (error instanceof ServletException && error.getCause() != null) {error = error.getCause();}}// todo 判断和处理错误类型Integer status = getAttribute(webRequest, RequestDispatcher.ERROR_STATUS_CODE);String msg = getAttribute(webRequest, RequestDispatcher.ERROR_MESSAGE);if (StringUtils.isEmpty(msg) && error != null) {msg = error.getMessage();}// todo 返回失败的Response对象log.info("msg = {}, status = {}", msg, status);return null;}@SuppressWarnings("unchecked")private <T> T getAttribute(RequestAttributes requestAttributes, String name) {return (T) requestAttributes.getAttribute(name, RequestAttributes.SCOPE_REQUEST);}
}
代码详解
这里我们扩展了一个
CustomErrorAttributes
类,并用@Component
来修饰为一个sprin的bean
组件,它从DefaultErrorAttributes
继承,它们都实现了ErrorAttributes
接口,当spring boot在启动的时候,发现用户有实现该接口的类并配置为一个组件时,就会用用户扩展的而非默认的实现。这里,我们重写
getErrorAttributes
方法,并在其中调用了一个私有的构建错误响应对象的buildErrResp
方法,在该方法中,我们参考了父类DefaultErrorAttributes
中如何获取错误信息的相关代码,比如获取抛出来的错误对象error
的逻辑代码就来自于父类,getError(webRequest)
方法来自于父类,这里获取到的error
对象可能是经过多层包装的,需要判断并循环调用getCause()
以获得最原始的错误对象,getAttribute
方法也是从父类移植过来的,用来从请求的作用域中获取提前设置好的http响应状态status
和错误信息msg
,如果msg
无法从预设中获取到,并且错误对象不为空,则调用错误对象的getMessage()
方法返回的信息作为错误信息。最后,我们将基于http错误状态码和错误信息来构建一个
Response
对象,这部分待实现。构建出来的错误响应对象
errResp
,需要放到作为返回结果的Map
中,这里的key我们可以任意指定,这个Map
对象最终会作为参数传递给我们先前实现的RestBodyAdvice
类的beforeBodyWrite
方法,以便我们可以拿到构建好的Response
类型的错误响应对象进行响应,为此,这里我们将这个key抽取为一个包级别可访问的ERR_RESP_KEY
静态成员变量。
Response中增加错误信息
这里的错误消息msg
对于正确响应来说是空的,是不用参与json序列化的;代表http响应状态的枚举类型HttpStatus
也不用参与序列化,因此用了@JsonIgnore
注解来忽略;这里还提供了一个静态fail
方法来进行错误响应对象的包装。
package com.juan.demo.common.dto;import ......
public class Response<T> {...@JsonInclude(JsonInclude.Include.NON_EMPTY)private String msg;...@JsonIgnoreprivate HttpStatus httpStatus;...private static final Integer STATUS_FAIL = 1;...public static Response<?> fail(String msg, Integer statusCode) {Response<?> errResp = new Response<>();errResp.setStatus(STATUS_FAIL);errResp.setMsg(msg);if (statusCode != null) {errResp.setHttpStatus(HttpStatus.valueOf(statusCode));}return errResp;}...}
然后,CustomErrorAttributes
类的buildErrResp
方法的返回值,这样包装:
private Response<?> buildErrResp(WebRequest webRequest) {...return Response.fail(msg, status);
}
在RestBodyAdvice
类的beforeBodyWrite
方法中,对传入的Object
类型的body
参数进行判断,如果是我们之前包装好的包含err_resp
的key的错误响应Map
,则从中获取错误响应对象进行响应设置:
package com.juan.demo.common.web.support;import ...import static com.juan.demo.common.web.support.CustomErrorAttributes.ERR_RESP_KEY;...
public class RestBodyAdvice implements ResponseBodyAdvice<Object> {......public Object beforeBodyWrite(Object body, ...) {if (body instanceof Map && ((Map<?, ?>) body).containsKey(ERR_RESP_KEY)) {Response<?> errResp = (Response<?>) ((Map<?, ?>) body).get(ERR_RESP_KEY);if (errResp.getHttpStatus() != null) response.setStatusCode(errResp.getHttpStatus());return errResp;}// 正确响应处理代码省略...}
}
验证响应404错误
启动服务测试一个不存在的地址,看到预期的404错误信息:
响应自定义异常
为了可以响应自定义异常BusinessException
抛出的操作信息,我们需要在CustomErrorAttributes
的buildErrResp
方法中判断异常类型并进行错误响应对象的包装:
private Response<?> buildErrResp(WebRequest webRequest) {// 获取错误对象的代码省略Throwable error = ...// 判断和处理错误类型if (error instanceof BusinessException) {BusinessException be = (BusinessException) error;return Response.fail(be);}...
}
在Response
类中再提供一个相应的fail
重载方法:
public static Response<?> fail(BusinessException ex) {Response<?> errResp = new Response<>();errResp.setStatus(STATUS_FAIL);errResp.setMsg(ex.getMessage());errResp.setHttpStatus(HttpStatus.INTERNAL_SERVER_ERROR);return errResp;
}
重启服务,再次测试下添加购物车服务,响应的结果符合我们的预期。
完善自定义异常和错误响应类字段
相对于之前的版本,这里新引入了一个errCode
的字段来保存要响应给前端的错误码信息。对于重载的构造和静态fail
方法,因为扩展了字段,这里提供最全的重载方法,其他重载则调用合适的重载方法即可。另外接收BusinessException
类型的fail
方法,在完成转换时,需要在BusinessException
中也扩展相应的字段。
package com.juan.demo.common.dto;import ......
public class Response<T> {...@JsonInclude(JsonInclude.Include.NON_EMPTY)private String errCode;...private Response(Integer status, String msg, String errCode, T data, HttpStatus httpStatus) {this.status = status;this.msg = msg;this.errCode = errCode;this.data = data;this.httpStatus = httpStatus;}private Response(Integer status, T data) {// 改成调用重载构造this(status, null, null, data, null);}...// 增加fail重载方法public static <T> Response<T> fail(String msg, String errCode, T data, HttpStatus httpStatus) {// 调用最全的构造return new Response<>(STATUS_FAIL, msg, errCode, data, httpStatus);}public static <T> Response<T> fail(String msg, String errCode, T data) {return fail(msg, errCode, data, null);}public static Response<?> fail(String msg, String errCode) {return fail(msg, errCode,null);}public static Response<?> fail(String msg) {return fail(msg,null, null);}public static Response<?> fail(BusinessException ex) {// todo 这里的后3个参数都要从异常对象ex中获取,暂时硬编码写死return fail(ex.getMessage(), null, null, HttpStatus.INTERNAL_SERVER_ERROR);}public static Response<?> fail(String msg, Integer statusCode) {Response<?> errResp = fail(msg);...}...}
Response
完善后的字段:
-
status
响应状态,0-成功,1-失败
-
errCode
错误响应时携带的错误码,可为空,为空时不输出到json
-
msg
响应的错误消息,正常响应时该字段为空,且不输出到json
-
data
实际响应的数据,为空时不输出到json
-
httpStatus
要设置给响应对象的http状态码枚举类型,不输出到json
注意,除了无参构造是public的,其他都是private的,这样只允许外部通过调用静态的ok
或fail
方法来构造实例
扩展BusinessException
字段:
package com.juan.demo.common.exception;import ...@Getter
public class BusinessException extends RuntimeException {private String errCode;@Nullableprivate Object data;private HttpStatus status = HttpStatus.INTERNAL_SERVER_ERROR;public BusinessException(String msg, String errCode, Object data, HttpStatus status) {super(msg);this.errCode = errCode;this.data = data;this.status = status;}public BusinessException(String msg, String errCode, Object data) {this(msg, errCode, data, null);}public BusinessException(String msg, String errCode) {this(msg, errCode, null);}public BusinessException(String msg, HttpStatus status) {this(msg);this.status = status;}...}
在BusinessException
类中完善字段:
-
errCode
业务错误码,可在枚举类中维护。抛出异常时,可指定或者不指定
-
data
抛出异常时携带的相关的数据信息,可以为空
-
status
http的状态码,默认为500,可在抛出异常时,自己指定
增加重载的构造器,在构造器内部可以调用其他构造器完成已有属性的初始化。
不要忘了在类上加@Getter
注解,来提供属性的getter方法。
最后,再调整下Response
类中转换BusinessException
对象的方法:
public static Response<?> fail(BusinessException ex) {return fail(ex.getMessage(), ex.getErrCode(), ex.getData(), ex.getStatus());
}
完成这些调整后,我们做一个测试,对CartController
中的addCartItem
方法,直接返回一个认证失败的异常:
package com.juan.demo.web.controller;import ......
public class CartController implements CartAPI {......public void addCartItem(CartItemDTO cartItemDTO) {throw new BusinessException("请先登录", HttpStatus.UNAUTHORIZED);// 注释掉后续代码...}
}
启动服务,测试添加购物车接口。
甚至,我们可以在抛出异常时指定业务错误码:
throw new BusinessException("请先登录", "555", null, HttpStatus.UNAUTHORIZED);
测试输出:
记录错误响应日志
在响应体信息拦截的RestBodyAdvice
类中加一个记录响应对象日志信息的私有方法:
@SneakyThrows
private Response<?> logResp(Response<?> resp) {log.info("============ 响应结果:{}", objectMapper.writeValueAsString(resp));return resp;
}
把传入的对象返回,调用这个包装方法的3处地方:
public Object beforeBodyWrite(...) {// 判断是错误响应的情况if (...) {Response<?> errResp = ......return logResp(errResp); // 第1处}...// 字符串响应的情况if (type == String.class) {...return objectMapper.writeValueAsString(logResp(Response.ok(body))); // 第2处}return logResp(Response.ok(body)); // 第3处
}
测试错误日志输出:
总结
通过一步步的实践,我们完成了基于spring boot
对异常处理现有流程的扩展,后续我们还将在这个扩展基础上继续增加数据校验相关的异常信息组织方式。通过不断的完善,这种异常处理的基础架构我们可以封装成common-starter
起始依赖,让小伙伴们在企业级项目中得到应用。大家加油!