当前位置：首页 > news >正文

Spring Boot 3.x Rest API统一异常处理最佳实践

news 2025/7/7 0:14:53

上一篇：Spring Boot 3.x Rest API最佳实践之统一响应结构

下一篇：Spring Boot 3.x Web单元测试最佳实践

参考著作：Error Handling for REST with Spring

在Spring MVC应用中，要对web表示层所抛出的异常进行捕获处理有多种方式，具体的可参考著名国外Spring技术实战网站baeldung上的相关话题。Spring Boot对Spring MVC应用中抛出的异常以及http错误的捕获处理流程做了统一的封装，最终以特定的json结构响应给前端，而我们要做的只是扩展它对json结果的包装方式，以我们想要的结构返回即可。

接下来的实践，我们将自定义异常、业务错误码以及错误响应结构三者融合起来，实现定制化的企业级统一异常处理方案。如果觉得对你有帮助，记得点赞收藏，关注小卷，后续更精彩！

在这里插入图片描述

文章目录

- 定义和抛出自定义异常
- 扩展DefaultErrorAttributes
- Response中增加错误信息
- 验证响应404错误
- 响应自定义异常
- 完善自定义异常和错误响应类字段
- 记录错误响应日志
- 总结

定义和抛出自定义异常

自定义一个异常，从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处
}