快捷導(dǎo)航

Spring Boot 中的默認異常處理機制及執(zhí)行流程

更新時間：2025年07月24日 11:19:22 作者：MadeInSQL

SpringBoot內(nèi)置BasicErrorController,自動處理異常并生成HTML/JSON響應(yīng),支持自定義錯誤路徑、配置及擴展,如ErrorController和@ControllerAdvice,實現(xiàn)靈活的錯誤處理機制,對Spring Boot 默認異常處理機制相關(guān)知識感興趣的朋友一起看看吧

Spring Boot 異常處理機制詳解

Spring Boot 提供了一套完善的默認異常處理機制，通過內(nèi)置的 BasicErrorController 自動處理應(yīng)用中的各類異常情況。這套機制基于 Spring MVC 的異常處理框架構(gòu)建，具有以下特點：

多格式響應(yīng)支持：
- 對于傳統(tǒng)Web應(yīng)用：當發(fā)生異常時，會自動返回錯誤頁面（如 404.html、5xx.html）
- 對于REST API：會自動生成結(jié)構(gòu)化的JSON錯誤響應(yīng)，包含timestamp、status、error、path等字段
默認錯誤路徑：
- 提供了/error映射路徑作為統(tǒng)一的錯誤處理入口
- 可以通過實現(xiàn)ErrorController接口來自定義錯誤處理邏輯
錯誤頁面配置：
- 靜態(tài)錯誤頁：支持在src/main/resources/static/error/目錄下放置靜態(tài)錯誤頁
- 模板錯誤頁：支持在模板引擎目錄（如templates/error/）下放置動態(tài)錯誤頁
- 支持根據(jù)狀態(tài)碼命名文件（如404.html、500.html）
內(nèi)置異常轉(zhuǎn)換：
- 自動將常見異常轉(zhuǎn)換為合適的HTTP狀態(tài)碼
- 例如：MethodArgumentNotValidException -> 400 Bad Request
- 例如：NoHandlerFoundException -> 404 Not Found
配置選項：
- 通過server.error.*配置項可以自定義錯誤處理行為
- 例如：server.error.include-message=always（控制錯誤信息是否包含詳細異常信息）

實際應(yīng)用示例：

// 自定義錯誤頁
@Controller
public class MyErrorController implements ErrorController {
    @RequestMapping("/error")
    public String handleError(HttpServletRequest request) {
        Object status = request.getAttribute("javax.servlet.error.status_code");
        if (status != null) {
            Integer statusCode = Integer.valueOf(status.toString());
            if(statusCode == 404) {
                return "error/404";
            } else if(statusCode == 500) {
                return "error/500";
            }
        }
        return "error/generic";
    }
}

這套機制既適用于傳統(tǒng)Web應(yīng)用的頁面錯誤展示，也適配RESTful API的JSON錯誤響應(yīng)，為開發(fā)者提供了開箱即用的異常處理解決方案。

默認錯誤頁面功能

當應(yīng)用出現(xiàn)異常時，Spring Boot 會自動展示一個"Whitelabel Error Page"（白色標簽錯誤頁），這個頁面包含以下關(guān)鍵信息：

HTTP狀態(tài)碼（如404、500等）
錯誤發(fā)生的時間戳（精確到毫秒）
具體的錯誤信息（異常消息）
請求的URL路徑
錯誤跟蹤ID（便于日志關(guān)聯(lián)）

例如：

訪問不存在的URL時，會返回一個包含"404 Not Found"狀態(tài)的錯誤頁面
服務(wù)器內(nèi)部錯誤時會顯示500錯誤頁面，并附帶相關(guān)錯誤信息
參數(shù)驗證失敗時會返回400錯誤頁面

自動異常轉(zhuǎn)換機制

Spring Boot 會自動將常見的異常類型轉(zhuǎn)換為合適的HTTP狀態(tài)碼：

404 Not Found
- 觸發(fā)條件：NoHandlerFoundException
- 使用場景：當請求的URL沒有對應(yīng)的控制器方法時
- 示例：訪問 /api/non-existent-endpoint
400 Bad Request
- 觸發(fā)條件：MethodArgumentNotValidException（方法參數(shù)驗證失?。?/li>
- 使用場景：表單驗證失敗、REST API參數(shù)校驗不通過
- 示例：提交的JSON數(shù)據(jù)缺少必填字段
500 Internal Server Error
- 觸發(fā)條件：其他所有未捕獲的異常
- 使用場景：業(yè)務(wù)邏輯中的運行時異常
- 示例：數(shù)據(jù)庫連接失敗、空指針異常

錯誤屬性配置選項

開發(fā)者可以通過 application.properties 或 application.yml 文件自定義錯誤處理行為：

# 控制錯誤信息中是否包含異常消息
server.error.include-message=always # 可選值：always, on_param, never
# 控制是否包含堆棧跟蹤信息
server.error.include-stacktrace=on_param # 可選值：always, on_param, never
# 自定義錯誤處理路徑（默認為/error）
server.error.path=/custom-error
# 是否包含錯誤詳情（綁定異常的具體字段錯誤）
server.error.include-binding-errors=always

默認錯誤處理流程詳解

異常觸發(fā)階段
- 當應(yīng)用代碼中拋出異常且未被捕獲時
- 異常被Spring MVC的 DispatcherServlet 捕獲
請求轉(zhuǎn)發(fā)階段
- DispatcherServlet 將異常轉(zhuǎn)發(fā)到配置的錯誤路徑（默認是/error）
- 根據(jù)請求的Accept頭決定響應(yīng)格式（HTML或JSON）
錯誤處理階段
- BasicErrorController 處理該請求
- 收集錯誤信息（狀態(tài)碼、錯誤消息、時間戳等）
- 對于瀏覽器請求（Accept包含text/html），返回HTML錯誤頁
- 對于API請求（Accept包含application/json），返回JSON格式的錯誤信息

響應(yīng)生成階段 JSON響應(yīng)示例：

{
  "timestamp": "2023-05-15T08:12:34.567+00:00",
  "status": 404,
  "error": "Not Found",
  "path": "/api/non-existent"
}

擴展機制

雖然Spring Boot提供了默認處理，但開發(fā)者可以通過以下方式擴展：

自定義ErrorController
- 實現(xiàn)ErrorController接口
- 重寫getErrorPath()和error()方法
- 示例：記錄錯誤日志或發(fā)送告警通知

全局異常處理器

使用@ControllerAdvice注解定義全局異常處理類
配合@ExceptionHandler處理特定異常

示例：

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(value = {UserNotFoundException.class})
    protected ResponseEntity<ErrorResponse> handleUserNotFound(UserNotFoundException ex) {
        ErrorResponse error = new ErrorResponse("USER_NOT_FOUND", ex.getMessage());
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }
}