【SpringBoot教程】SpringBoot 統一異常處理(附核心工具類-ErrorInfoBuilder)

作者簡介：大家好，我是擼代碼的羊駝，前阿里巴巴架構師，現某互聯網公司CTO

聯系v：sulny_ann（17362204968），加我進群，大家一起學習，一起進步，一起對抗互聯網寒冬

# 序言

此前，我們主要通過在控制層（Controller）中手動捕捉異常（TryCatch）和處理錯誤，在SpringBoot 統一異常處理的做法主要有兩種：一是基于注解ExceptionHandler，二是基于接口ErrorController，兩者都可以讓控制器層代碼快速“瘦身”，讓業務邏輯看起來更加清晰明朗！

一. 默認錯誤處理

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;
@ControllerAdvicepublic 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)@Componentpublic 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@RestControllerpublic 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，啟動項目然后進行測試。本案例-項目結構圖如下：

三. 使用@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=truespring.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();    }}