SpringBoot 统一异常处理(附核心工具类-ErrorInfoBuilder)

序言：此前，我们主要通过在控制层（Controller）中手动捕捉异常（TryCatch）和处理错误，在SpringBoot 统一异常处理的做法主要有两种：一是基于注解ExceptionHandler，二是基于接口ErrorController，两者都可以让控制器层代码快速“瘦身”，让业务逻辑看起来更加清晰明朗！本工程传送门：SpringBoot-Exception-Handler

一. 默认错误处理

SpringBoot 默认为我们提供了BasicErrorController 来处理全局错误/异常，并在Servlet容器中注册error为全局错误页。所以在浏览器端访问，发生错误时，我们能及时看到错误/异常信息和HTTP状态等反馈。工作原理如下：

@Controller
@RequestMapping("${server.error.path:${error.path:/error}}")
public class BasicErrorController extends AbstractErrorController {
    // 统一异常处理（View）
    @RequestMapping(produces = "text/html")
    public ModelAndView errorHtml(HttpServletRequest request,
            HttpServletResponse response) {
        HttpStatus status = getStatus(request);
        Map<String, Object> model = Collections.unmodifiableMap(getErrorAttributes(
                request, isIncludeStackTrace(request, MediaType.TEXT_HTML)));
        response.setStatus(status.value());
        ModelAndView modelAndView = resolveErrorView(request, response, status, model);
        return (modelAndView == null ? new ModelAndView("error", model) : modelAndView);
    }

例如下面这两个错误，对于日常开发而言，再熟悉不过了。

404 Not Found

500 服务器错误

二. 统一异常处理

默认的英文空白页，显然不能够满足我们复杂多变的需求，因此我们可以通过专门的类来收集和管理这些异常信息，这样做不仅可以减少控制层的代码量，还有利于线上故障排查和紧急短信通知等。

具体步骤

为了让小伙伴少走一些弯路，楼主根据官方源码和具体实践，提炼这些核心工具类：

ErrorInfo 错误信息
ErrorInfoBuilder 错误信息的构建工具

注：在CSDN和大牛博客中，不乏关于Web应用的统一异常处理的教程，但更多的是基础学习使用，并不能投入实际项目使用，为了让大家少走一些弯路和快速投入生产，楼主根据官方源码和项目实践，提炼出了核心工具类（ErrorInfoBuilder ），将构建异常信息的逻辑从异常处理器/控制器中抽离出来，让大家通过短短几行代码就能获取丰富的异常信息，更专注于业务开发！！

1. 统一异常处理器(GlobalErrorHandler)

@ControllerAdvice 限定范围例如扫描某个控制层的包
@ExceptionHandler 指定异常例如指定处理运行异常。

具体如下：

package com.hehe.error;

@ControllerAdvice
public class GlobalErrorHandler {

    private final static String DEFAULT_ERROR_VIEW = "error";//错误信息页

    @Autowired
    private ErrorInfoBuilder errorInfoBuilder;//错误信息的构建工具

    /**
     * 根据业务规则,统一处理异常。
     */
    @ExceptionHandler(Exception.class)
    @ResponseBody
    public Object exceptionHandler(HttpServletRequest request, Throwable error) {

        //1.若为AJAX请求,则返回异常信息(JSON)
        if (isAjaxRequest(request)) {
           return errorInfoBuilder.getErrorInfo(request,error);
        }
        //2.其余请求,则返回指定的异常信息页(View).
        return new ModelAndView(DEFAULT_ERROR_VIEW, "errorInfo", errorInfoBuilder.getErrorInfo(request, error));
    }

    private boolean isAjaxRequest(HttpServletRequest request) {

        return "XMLHttpRequest".equals(request.getHeader("X-Requested-With"));
    }

}

2. 统一异常信息（ErrorInfo）

虽然官方提供了ErrorAttributes来存储错误信息，但其返回的是存储结构是Map<String,Object>，为了更好的服务统一异常，这里我们统一采用标准的ErrroInfo来记载错误信息。

package com.hehe.error;

public class ErrorInfo {

    private String time;//发生时间
    private String url;//访问Url
    private String error;//错误类型
    String stackTrace;//错误的堆栈轨迹
    private int statusCode;//状态码
    private String reasonPhrase;//状态码

    //Getters And Setters
       ...
  
}

3. 统一异常信息的构建工具（ErrorInfoBuilder）

ErrorInfoBuilder 作为核心工具类，其意义不言而喻，重点API：

获取错误/异常
通信状态
堆栈轨迹

注：正确使用ErrorInfoBuilder，可以让处理器减少80%的代码。总而言之，ErrorInfoBuilder是个好东西，值得大家细细琢磨。

package com.hehe.error;

@Order(Ordered.HIGHEST_PRECEDENCE)
@Component
public class ErrorInfoBuilder implements HandlerExceptionResolver, Ordered {

    /**
     * 错误KEY
     */
    private final static String ERROR_NAME = "hehe.error";

    /**
     * 错误配置(ErrorConfiguration)
     */
    private ErrorProperties errorProperties;

    public ErrorProperties getErrorProperties() {
        return errorProperties;
    }

    public void setErrorProperties(ErrorProperties errorProperties) {
        this.errorProperties = errorProperties;
    }

    /**
     * 错误构造器 (Constructor) 传递配置属性：server.xx -> server.error.xx
     */
    public ErrorInfoBuilder(ServerProperties serverProperties) {
        this.errorProperties = serverProperties.getError();
    }

    /**
     * 构建错误信息.(ErrorInfo)
     */
    public ErrorInfo getErrorInfo(HttpServletRequest request) {

        return getErrorInfo(request, getError(request));
    }

    /**
     * 构建错误信息.(ErrorInfo)
     */
    public ErrorInfo getErrorInfo(HttpServletRequest request, Throwable error) {
        ErrorInfo errorInfo = new ErrorInfo();
        errorInfo.setTime(LocalDateTime.now().toString());
        errorInfo.setUrl(request.getRequestURL().toString());
        errorInfo.setError(error.toString());
        errorInfo.setStatusCode(getHttpStatus(request).value());
        errorInfo.setReasonPhrase(getHttpStatus(request).getReasonPhrase());
        errorInfo.setStackTrace(getStackTraceInfo(error, isIncludeStackTrace(request)));
        return errorInfo;
    }

    /**
     * 获取错误.(Error/Exception)
     *
     * @see DefaultErrorAttributes #addErrorDetails
     */
    public Throwable getError(HttpServletRequest request) {
        //根据HandlerExceptionResolver接口方法来获取错误.
        Throwable error = (Throwable) request.getAttribute(ERROR_NAME);
        //根据Request对象获取错误.
        if (error == null) {
            error = (Throwable) request.getAttribute(WebUtils.ERROR_EXCEPTION_ATTRIBUTE);
        }
        //当获取错误非空,取出RootCause.
        if (error != null) {
            while (error instanceof ServletException && error.getCause() != null) {
                error = error.getCause();
            }
        }//当获取错误为null,此时我们设置错误信息即可.
        else {
            String message = (String) request.getAttribute(WebUtils.ERROR_MESSAGE_ATTRIBUTE);
            if (StringUtils.isEmpty(message)) {
                HttpStatus status = getHttpStatus(request);
                message = "Unknown Exception But " + status.value() + " " + status.getReasonPhrase();
            }
            error = new Exception(message);
        }
        return error;
    }

    /**
     * 获取通信状态(HttpStatus)
     *
     * @see AbstractErrorController #getStatus
     */
    public HttpStatus getHttpStatus(HttpServletRequest request) {
        Integer statusCode = (Integer) request.getAttribute(WebUtils.ERROR_STATUS_CODE_ATTRIBUTE);
        try {
            return statusCode != null ? HttpStatus.valueOf(statusCode) : HttpStatus.INTERNAL_SERVER_ERROR;
        } catch (Exception ex) {
            return HttpStatus.INTERNAL_SERVER_ERROR;
        }
    }

    /**
     * 获取堆栈轨迹(StackTrace)
     *
     * @see DefaultErrorAttributes  #addStackTrace
     */
    public String getStackTraceInfo(Throwable error, boolean flag) {
        if (!flag) {
            return "omitted";
        }
        StringWriter stackTrace = new StringWriter();
        error.printStackTrace(new PrintWriter(stackTrace));
        stackTrace.flush();
        return stackTrace.toString();
    }

    /**
     * 判断是否包含堆栈轨迹.(isIncludeStackTrace)
     *
     * @see BasicErrorController #isIncludeStackTrace
     */
    public boolean isIncludeStackTrace(HttpServletRequest request) {

        //读取错误配置(server.error.include-stacktrace=NEVER)
        IncludeStacktrace includeStacktrace = errorProperties.getIncludeStacktrace();

        //情况1：若IncludeStacktrace为ALWAYS
        if (includeStacktrace == IncludeStacktrace.ALWAYS) {
            return true;
        }
        //情况2：若请求参数含有trace
        if (includeStacktrace == IncludeStacktrace.ON_TRACE_PARAM) {
            String parameter = request.getParameter("trace");
            return parameter != null && !"false".equals(parameter.toLowerCase());
        }
        //情况3：其它情况
        return false;
    }

    /**
     * 保存错误/异常.
     *
     * @see DispatcherServlet #processHandlerException 进行选举HandlerExceptionResolver
     */
    @Override
    public ModelAndView resolveException(HttpServletRequest request, HttpServletResponse response, @Nullable Object handler, Exception ex) {
        request.setAttribute(ERROR_NAME, ex);
        return null;
    }

    /**
     * 提供优先级 或用于排序
     */
    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE;
    }
}

注：ErrorBuilder之所以使用@Order注解和实现HandlerExceptionResolver接口是为了获取错误/异常，通常情况下@ExceptionHandler并不需要这么做，因为在映射方法注入Throwable就可以获得错误/异常，这是主要是为了ErrorController根据Request对象快速获取错误/异常。

4. 控制层代码（Controller）

上述，错误/异常处理器、错误信息、错误信息构建工具全部完成，我们编写控制层代码来测试相关效果。

package com.hehe;

@SpringBootApplication
@RestController
public class ErrorHandlerApplication {
    /**
     * 随机抛出异常
     */
    private void randomException() throws Exception {
        Exception[] exceptions = { //异常集合
                new NullPointerException(),
                new ArrayIndexOutOfBoundsException(),
                new NumberFormatException(),
                new SQLException()};
        //发生概率
        double probability = 0.75;
        if (Math.random() < probability) {
            //情况1：要么抛出异常
            throw exceptions[(int) (Math.random() * exceptions.length)];
        } else {
            //情况2：要么继续运行
        }

    }

    /**
     * 模拟用户数据访问
     */
    @GetMapping("/")
    public List index() throws Exception {
        randomException();
        return Arrays.asList("正常用户数据1!", "正常用户数据2! 请按F5刷新!!");
    }

    public static void main(String[] args) {
        SpringApplication.run(ErrorHandlerApplication.class, args);
    }
}

5. 页面代码（Thymeleaf）

代码完成之后，我们需要编写一个异常信息页面。为了方便演示，我们在resources目录下创建templates目录，并新建文件exception.html。页面代码如下：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>GlobalError</title>
</head>
<h1>统一祖国 振兴中华</h1>
<h2>服务异常，请稍后再试。</h2>
<div th:object="${errorInfo}">
    <h3 th:text="*{'发生时间：'+time}"></h3>
    <h3 th:text="*{'访问地址：'+url}"></h3>
    <h3 th:text="*{'问题类型：'+error}"></h3>
    <h3 th:text="*{'通信状态：'+statusCode+','+reasonPhrase}"></h3>
    <h3 th:text="*{'堆栈信息：'+stackTrace}"></h3>
</div>
</body>
</html>

注：SpringBoot默认支持很多种模板引擎（如Thymeleaf、FreeMarker），并提供了相应的自动配置，做到开箱即用。默认的页面加载路径是 src/main/resources/templates ，如果放到其它目录需在配置文件指定。（举例：spring.thymeleaf.prefix=classpath:/views/ ）

6. 引入依赖（POM文件）

以前操作之前，不要忘了在pom.xml 引入相关依赖：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <!--基本信息 -->
    <groupId>com.hehe</groupId>
    <artifactId>springboot-error-handler</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>
    <name>spring-boot-error-handler</name>
    <description>SpringBoot 统一异常处理</description>

    <!--继承信息 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.0.M4</version>
        <relativePath/>
    </parent>

    <!--依赖管理 -->
    <dependencies>
        <dependency> <!--添加Web依赖 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency> <!--添加Thymeleaf依赖 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
        <dependency><!--添加Test依赖 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!--指定远程仓库（含插件）-->
    <repositories>
        <repository>
            <id>spring-snapshots</id>
            <url>http://repo.spring.io/snapshot</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>spring-milestones</id>
            <url>http://repo.spring.io/milestone</url>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>spring-snapshots</id>
            <url>http://repo.spring.io/snapshot</url>
        </pluginRepository>
        <pluginRepository>
            <id>spring-milestones</id>
            <url>http://repo.spring.io/milestone</url>
        </pluginRepository>
    </pluginRepositories>

    <!--构建插件 -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

7. 开始测试

上述步骤完成之后，打开启动类GlobalExceptionApplication，启动项目然后进行测试。本案例-项目结构图如下：

测试效果：在浏览器输入 http://localhost:8080 多次按F5刷新，然后查看页面效果。截图如下：

三. 使用@ExceptionHandler的不足之处

关于实现Web应用统一异常处理的两种方法比较：

特性	@ExceptionHandler	ErrorController
获取异常	通过方法参数注入	通过ErrorInfoBuilder获取
返回类型	若请求的类型为Ajax则返回JSON，否则返回页面.	若请求的媒介类型为HTML 则返回页面，否则返回JSON.
缺点	无法处理404类异常	很强大，可处理全部错误/异常

1. 使用@ExceptionHandler 为什么无法处理404错误/异常？

答：因为SpringMVC优先处理（Try Catch）掉了资源映射不存在的404类错误/异常，虽然在响应信息注入了404的HttpStatus通信信息，但木有了异常，肯定不会进入@ExceptionHandler 的处理逻辑。

2. 使用@ExceptionHandler + 抛出异常是否可取？

答：由上图可知@ExceptionHanlder的最大不足之处是无法直接捕获404背后的异常，网上流传通过取消资源目录映射来解决无404问题是不可取的，属于越俎代庖的做法。

spring.mvc.throw-exception-if-no-handler-found=true
spring.resources.add-mappings=false

3. 为什么推荐ErrorController 替代 @ExceptionHandler ?

使用ErrorController可以处理全部错误/异常。
使用ErrorController+ErrorInfoBuilder 在单个方法里面可以针对不同的Exception来添加详细的错误信息，具体做法：拓展ErrorInfoBuilder的getErrorInfo方法来添加错误信息（例如：ex instanceof NullPointerException Set xxx）。

注意：实际上，目前SpringBoot官方就是通过ErrorController来做的统一错误/异常处理，但遗憾的是，关于这方面的官方文档并没有给出详细示例，仅仅是一笔带过，大概官方认为@ExceptionHandler 够用？？而网上也甚少人具体提及ErrorController和ErrorAttribute 背后一整套的实现逻辑，也正是如此，促使楼主决心写下这篇文章，希望给大家带来帮助，少走一些弯路！！

四. 使用ErrorController替代@ExceptionHandler

4. 如何快速使用 ErrorController ？

回答：经过楼主的精心设计，ErrorInfoBuilder 可以无缝对接ErrorController （即上述两种错误/异常处理均共用此工具类），你只需要做的是：将本案例的ErrorInfo和ErrorInfoBuilder 拷贝进项目，简单编写ErrorController 跳转页面和返回JSON即可。具体如下：

@RequestMapping(produces = MediaType.TEXT_HTML_VALUE)
说明：produces属性作为匹配规则：表示Request请求的Accept头部需含有text/html。
用途：text/html 主要用于响应普通的页面请求，与AJAX请求作为区分。

package com.hehe.error;

@Controller
@RequestMapping("${server.error.path:/error}")
public class GlobalErrorController implements ErrorController {
    
@Autowired
    private ErrorInfoBuilder errorInfoBuilder;//错误信息的构建工具.

    private final static String DEFAULT_ERROR_VIEW = "error";//错误信息页

    /**
     * 情况1：若预期返回类型为text/html,则返回错误信息页(View).
     */
    @RequestMapping(produces = MediaType.TEXT_HTML_VALUE)
    public ModelAndView errorHtml(HttpServletRequest request) {
        return new ModelAndView(DEFAULT_ERROR_VIEW, "errorInfo", errorInfoBuilder.getErrorInfo(request));
    }

    /**
     * 情况2：其它预期类型 则返回详细的错误信息(JSON).
     */
    @RequestMapping
    @ResponseBody
    public ErrorInfo error(HttpServletRequest request) {
        return errorInfoBuilder.getErrorInfo(request);
    }

    @Override
    public String getErrorPath() {//获取映射路径
        return errorInfoBuilder.getErrorProperties().getPath();
    }
}

注：是不是非常简单，相信这个工具类可以改变你对ErrorController复杂难用的看法。如果后续想拓展不同种类的错误/异常信息，只需修改ErrorInfoBuilder#getError方法即可，无需修改ErrorController的代码，十分方便。

五. 源码和文档

源码下载：SpringBoot-ErrorController

源码下载：SpringBoot-ExceptionHandler

专题阅读：《SpringBoot 布道系列》

最后编辑于：2017.11.16 00:32:03

人面猴
序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
沈念sama阅读 162,158评论 4赞 370
死咒
序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
沈念sama阅读 68,600评论 1赞 307
救了他两次的神仙让他今天三更去死
文/潘晓璐我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
开封第一讲书人阅读 111,785评论 0赞 254
道士缉凶录：失踪的卖姜人
文/不坏的土叔我叫张陵，是天一观的道长。经常有香客问我，道长，这世上最难降的妖魔是什么？我笑而不...
开封第一讲书人阅读 44,655评论 0赞 220
港岛之恋（遗憾婚礼）
正文为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
茶点故事阅读 53,075评论 3赞 295
恶毒庶女顶嫁案：这布局不是一般人想出来的
文/花漫我一把揭开白布。她就那样静静地躺着，像睡着了一般。火红的嫁衣衬着肌肤如雪。梳的纹丝不乱的头发上，一...
开封第一讲书人阅读 41,002评论 1赞 225
城市分裂传说
那天，我揣着相机与录音，去河边找鬼。笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。我是一名探鬼主播，决...
沈念sama阅读 32,146评论 2赞 318
双鸳鸯连环套：你想象不到人心有多黑
文/苍兰香墨我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
开封第一讲书人阅读 30,918评论 0赞 211
万荣杀人案实录
序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
沈念sama阅读 34,671评论 1赞 250
护林员之死
正文独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋以下内容为张勋视角年9月15日...
茶点故事阅读 30,838评论 2赞 254
白月光启示录
正文我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
茶点故事阅读 32,318评论 1赞 265
活死人
序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
沈念sama阅读 28,636评论 3赞 263
日本核电站爆炸内幕
正文年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
茶点故事阅读 33,343评论 3赞 244
男人毒药：我在死后第九天来索命
文/蒙蒙一、第九天我趴在偏房一处隐蔽的房顶上张望。院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
开封第一讲书人阅读 26,187评论 0赞 8
一桩弑父案，背后竟有这般阴谋
文/苍兰香墨我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。一阵脚步声响...
开封第一讲书人阅读 26,982评论 0赞 201
情欲美人皮
我被黑心中介骗来泰国打工，没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。一个月前我还...
沈念sama阅读 36,126评论 2赞 285
代替公主和亲
正文我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
茶点故事阅读 35,934评论 2赞 279