Spring Boot 全局异常处理（上）

背景

对接的项目多了，奇奇怪怪的问题就都出现了，比如有一个最让人烦心的问题 异常。

偶尔会碰到框架抛出的默认的异常，比如 Laraval，比如 Spring Boot，每个框架抛出的异常格式是不一致的，有 Json 或 XML 格式的数据，更甚至有 HTML 页面，最为关键的是响应的数据结构和接口约定的数据结构不一致，所以这时候我们在对响应内容进行解析的时候反而会给我们自己的代码带来需要处理的异常。

基于此，为了对自己的接口负责，我们需要进行全局的异常处理，目的是防止出现约定之外的数据结构。

Spring Boot 默认的异常处理机制

默认情况下，Spring Boot 会返回两种类型的异常，一种是 HTML，还有一种是 Json 格式的数据，这主要取决于请求头中的 Accept 参数，比如浏览器发出的请求，请求头中会附带 Accept：text/html，所以此时 Spring Boot 会返回一个错误页面，称为 Whitelabel Error Page，而当我们使用 Postman 请求时，返回的则是 Json 类型的数据。

原理其实也很简单，Spring Boot 默认提供了程序出错的结果映射路径 /error。而这个 /error 请求会由 BasicErrorController 来处理，其内部其实就是通过判断请求头的 Accept 中的内容来进行区分处理逻辑的（判断是否包含 text/html），从而来决定返回页面视图还是 JSON 消息内容。

相关 BasicErrorController 中代码如下：

BasicErrorController 处理逻辑

自定义错误页面

自定义错误页面的好处有好多，比如 404 错误页面，我们完全可以自定义 404 的 HTML 页面，上面可以放置图片等，这样体验就更友好一点。

自定义的错误页面有两种，一种是 静态页面，一种是使用 模板引擎 动态生成，后者的优势是可以在页面上显示自定义的内容。

• 静态页面的方式，html 文件的路径为：resources/public/error/xxx.html

如果要替换 404 错误页面，则在此路径下放置 404.html 文件，同理，如果要替换 500 错误页面，则在此路径下放置 500.html 文件即可

• 模板引擎渲染的动态页面的方式，html 文件的路径为：resources/templates/error/xxx.html

文件命名同上

注意：动态页面的优先级是要高于静态页面的
比如你同时配置了静态页面和动态页面，那么最终生效的，会是动态页面。

附上文件结构图：

文件结构

自定义错误信息

上面介绍了最简单的错误处理，最主要的针对返回的 HTML，但是我们往往也要处理 Json 类型的返回内容，目的是让数据结构和我们的接口返回的数据结构一致。

Step 1 自定义 servlet 容器

需要注意的是，Spring Boot 2.x 和 Sprig Boot 1.x 是不一样的。

此处 Demo 我们仅处理了 404 和 500 这两种异常。

@Configuration
public class ContainerConfig {

    /** 下面是 springboot 2.x 系列的写法 */
    @Bean
    public WebServerFactoryCustomizer<ConfigurableWebServerFactory> webServerFactoryCustomizer(){
        return factory -> {
            factory.addErrorPages(new ErrorPage(HttpStatus.INTERNAL_SERVER_ERROR, "/error/500"));
            factory.addErrorPages(new ErrorPage(HttpStatus.NOT_FOUND, "/error/404"));
        };
    }

    /** 下面是 springboot 1.x 系列的写法 */
    /*@Bean
    public EmbeddedServletContainerCustomizer containerCustomizer(){
        return new EmbeddedServletContainerCustomizer(){
            @Override
            public void customize(ConfigurableEmbeddedServletContainer container) {
                container.addErrorPages(new ErrorPage(HttpStatus.INTERNAL_SERVER_ERROR, "/error/500"));
                container.addErrorPages(new ErrorPage(HttpStatus.NOT_FOUND, "/error/404"));
            }
        };
    }*/
}

Step 2 自定义对应的请求处理类

@Controller
public class MyBasicErrorController extends BasicErrorController {

    public MyBasicErrorController() {
        super(new DefaultErrorAttributes(), new ErrorProperties());
    }

    /**
    * @Description: 定义500的ModelAndView
    * @Param: [request, response]
    * @return: org.springframework.web.servlet.ModelAndView 
    * @Author: Jet.Chen
    * @Date: 2019-07-17 21:56
    */
    @RequestMapping(produces = "text/html",value = "/500")
    public ModelAndView errorHtml500(HttpServletRequest request, HttpServletResponse response) {
        response.setStatus(getStatus(request).value());
        Map<String, Object> model = getErrorAttributes(request, isIncludeStackTrace(request, MediaType.TEXT_HTML));
        model.put("msg","自定义错误信息");
        return new ModelAndView("error/500", model);
    }


    /**
    * @Description: 定义500 和 404 的错误JSON信息
    * @Param: [request]
    * @return: org.springframework.http.ResponseEntity<cn.jetchen.steecrserver.config.STCRResposeData>
    * STCRResposeData 为全局统一的接口数据结构
    * @Author: Jet.Chen
    * @Date: 2019-07-17 23:13
    */
    @RequestMapping(value = {"/500", "/404"})
    @ResponseBody
    public ResponseEntity<STCRResposeData> error500(HttpServletRequest request) {
        Map<String, Object> body = getErrorAttributes(request, isIncludeStackTrace(request, MediaType.TEXT_HTML));
        HttpStatus status = getStatus(request);
        Object messageTemp;
        // stcrResposeData 为返回的数据
        STCRResposeData stcrResposeData = STCRResposeData.initError(
                String.format("%d%d", 1, status.value()), 
                (messageTemp = body.get("error")) == null ? null : messageTemp.toString(),
                new HashMap<String, Object>() {{
                    put("error", body.get("error"));
                    put("message", body.get("message"));
                }});
        return new ResponseEntity<>(stcrResposeData, status);
    }


    /**
    * @Description: 定义404的ModelAndView
    * @Param: [request, response]
    * @return: org.springframework.web.servlet.ModelAndView 
    * @Author: Jet.Chen
    * @Date: 2019-07-17 23:13
    */
    @RequestMapping(produces = "text/html",value = "/404")
    public ModelAndView errorHtml400(HttpServletRequest request, HttpServletResponse response) {
        response.setStatus(getStatus(request).value());
        Map<String, Object> model = getErrorAttributes(request, isIncludeStackTrace(request, MediaType.TEXT_HTML));
        model.put("msg","自定义错误信息");
        return new ModelAndView("error/404", model);
    }
}

小结

全局异常的处理是非常有必要的，但是此文到此的处理方式其实才完成了一半，这些会在下篇文章中介绍，主要是因为此处处理的是全局的错误，是在过滤器之外的，但是我们希望处理的粒度更细一点。

比如在控制器层的全局处理方式：@ControllerAdvice，从抽象概念上可以理解成它是处理那些在 Controller 方法中抛出的异常。