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

上一篇：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结果的包装方式，以我们想要的结构返回即可。

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

定义和抛出自定义异常

自定义一个异常，从RuntimeException继承，编译期无需处理。先考虑只用msg来构造。

package com.juan.demo.common.exception;

public class BusinessException extends RuntimeException {

    public BusinessException(String msg) {
        super(msg);
    }

}
1
2
3
4
5
6
7
8
9

在添加购物车的service方法中模拟抛出，启动服务，测试看响应结果。

...
public class CartServiceImpl implements CartService {
    
    @Override
    public List<CartItemDTO> addCartItem(CartItemDTO addItemDTO) {

        // 模拟抛出异常
        if (addItemDTO.getProductId() == 2) {
            throw new BusinessException("该商品已经下架，无法添加到购物车");
        }

        ...
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

测试发现输出的错误结构，包含在数据域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";

    @Override
    public 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);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

代码详解

这里我们扩展了一个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;

    ...

    @JsonIgnore
    private 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;
    }

    ...

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

然后，CustomErrorAttributes类的buildErrResp方法的返回值，这样包装：

private Response<?> buildErrResp(WebRequest webRequest) {
	...
    return Response.fail(msg, status);
}
1
2
3
4

在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;
        }

        // 正确响应处理代码省略...
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

验证响应404错误

启动服务测试一个不存在的地址，看到预期的404错误信息：

响应自定义异常

为了可以响应自定义异常BusinessException抛出的操作信息，我们需要在CustomErrorAttributes的buildErrResp方法中判断异常类型并进行错误响应对象的包装：

private Response<?> buildErrResp(WebRequest webRequest) {

    // 获取错误对象的代码省略
    Throwable error = ...

    // 判断和处理错误类型
    if (error instanceof BusinessException) {
        BusinessException be = (BusinessException) error;
        return Response.fail(be);
    }

    ...
}
1
2
3
4
5
6
7
8
9
10
11
12
13

在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;
}
1
2
3
4
5
6
7

重启服务，再次测试下添加购物车服务，响应的结果符合我们的预期。

完善自定义异常和错误响应类字段

相对于之前的版本，这里新引入了一个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);
        ...
    }

    ...

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

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;

    @Nullable
    private 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;
    }

    ...

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

在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());
}
1
2
3

完成这些调整后，我们做一个测试，对CartController中的addCartItem方法，直接返回一个认证失败的异常：

package com.juan.demo.web.controller;

import ...

...
public class CartController implements CartAPI {

    ...

    ...
    public void addCartItem(CartItemDTO cartItemDTO) {

        throw new BusinessException("请先登录", HttpStatus.UNAUTHORIZED);

		// 注释掉后续代码
		...
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

启动服务，测试添加购物车接口。

甚至，我们可以在抛出异常时指定业务错误码：

throw new BusinessException("请先登录", "555", null,  HttpStatus.UNAUTHORIZED);
1

测试输出：

记录错误响应日志

在响应体信息拦截的RestBodyAdvice类中加一个记录响应对象日志信息的私有方法：

@SneakyThrows
private Response<?> logResp(Response<?> resp) {
    log.info("============ 响应结果：{}", objectMapper.writeValueAsString(resp));
    return resp;
}
1
2
3
4
5

把传入的对象返回，调用这个包装方法的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处
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

测试错误日志输出：

总结

通过一步步的实践，我们完成了基于spring boot对异常处理现有流程的扩展，后续我们还将在这个扩展基础上继续增加数据校验相关的异常信息组织方式。通过不断的完善，这种异常处理的基础架构我们可以封装成common-starter起始依赖，让小伙伴们在企业级项目中得到应用。大家加油！