SpringBoot異常處理機(jī)制使用詳解
更新時(shí)間：2025年08月25日 11:08:56 作者：沒(méi)事學(xué)AI
SpringBoot異常處理基于Servlet與Spring框架,通過(guò)ErrorAttributes、ErrorViewResolver、BasicErrorController協(xié)作實(shí)現(xiàn)統(tǒng)一異常響應(yīng),企業(yè)級(jí)應(yīng)用需標(biāo)準(zhǔn)化異常體系,統(tǒng)一響應(yīng)格式,優(yōu)化性能與安全,如隱藏堆棧信息,確保日志上下文
一、異常處理的底層運(yùn)行機(jī)制
SpringBoot異常處理體系建立在Servlet容器與Spring框架的雙重基礎(chǔ)之上，通過(guò)一套精密的組件協(xié)作完成異常的捕獲、解析與響應(yīng)過(guò)程。理解這一機(jī)制的運(yùn)行脈絡(luò)，是進(jìn)行高級(jí)定制的前提。
1.1 異常捕獲的完整鏈路
SpringBoot通過(guò)錯(cuò)誤頁(yè)注冊(cè)器（ErrorPageRegistrar） 實(shí)現(xiàn)異常的初始捕獲。
該組件在應(yīng)用啟動(dòng)時(shí)自動(dòng)注冊(cè)，將所有未處理異常（包括4xx客戶端錯(cuò)誤和5xx服務(wù)器錯(cuò)誤）統(tǒng)一映射到/error端點(diǎn)。
這一過(guò)程包含三個(gè)關(guān)鍵步驟：
- 異常拋出：當(dāng)控制器方法拋出未捕獲的異常，或DispatcherServlet無(wú)法找到匹配的處理器（如404場(chǎng)景）時(shí)，觸發(fā)異常處理流程；
- 容器轉(zhuǎn)發(fā)：Servlet容器將異常封裝為
DispatcherType.ERROR類型的請(qǐng)求，轉(zhuǎn)發(fā)至/error路徑； - 端點(diǎn)接收：內(nèi)置的
BasicErrorController接收轉(zhuǎn)發(fā)請(qǐng)求，啟動(dòng)響應(yīng)生成流程。
實(shí)戰(zhàn)驗(yàn)證：在控制器中故意拋出異常
@GetMapping("/test-exception")
public String testException() {
if (true) {
throw new RuntimeException("模擬業(yè)務(wù)異常");
}
return "success";
}
訪問(wèn)該接口時(shí)，通過(guò)調(diào)試工具可觀察到請(qǐng)求先進(jìn)入控制器方法，拋出異常后被自動(dòng)轉(zhuǎn)發(fā)至/error路徑，最終由BasicErrorController處理。
1.2 響應(yīng)渲染的決策邏輯
BasicErrorController根據(jù)請(qǐng)求的Accept頭信息和客戶端類型，動(dòng)態(tài)選擇響應(yīng)渲染策略：
HTML響應(yīng)流程：
- 調(diào)用
errorHtml()方法獲取ModelAndView； - 通過(guò)
ErrorViewResolver解析合適的錯(cuò)誤頁(yè)面； - 渲染頁(yè)面并返回給瀏覽器客戶端。
JSON響應(yīng)流程：
- 調(diào)用
error()方法生成ResponseEntity<Map>； - 通過(guò)
ErrorAttributes收集錯(cuò)誤信息； - 序列化為JSON格式返回給API客戶端。
關(guān)鍵源碼解析：
// BasicErrorController核心方法
@RequestMapping(produces = MediaType.TEXT_HTML_VALUE)
public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) {
HttpStatus status = getStatus(request);
Map<String, Object> model = Collections.unmodifiableMap(getErrorAttributes(
request, getErrorAttributeOptions(request, MediaType.TEXT_HTML)));
response.setStatus(status.value());
ModelAndView modelAndView = resolveErrorView(request, response, status, model);
return (modelAndView != null) ? modelAndView : new ModelAndView("error", model);
}
@RequestMapping
public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
HttpStatus status = getStatus(request);
if (status == HttpStatus.NO_CONTENT) {
return new ResponseEntity<>(status);
}
Map<String, Object> body = getErrorAttributes(
request, getErrorAttributeOptions(request, MediaType.ALL));
return new ResponseEntity<>(body, status);
}
二、核心組件的協(xié)同工作原理
SpringBoot異常處理機(jī)制的靈活性，源于其模塊化的組件設(shè)計(jì)。每個(gè)組件承擔(dān)明確職責(zé)，同時(shí)通過(guò)接口定義預(yù)留擴(kuò)展點(diǎn)。
2.1 ErrorAttributes：錯(cuò)誤信息的標(biāo)準(zhǔn)化提取
ErrorAttributes是錯(cuò)誤信息的"數(shù)據(jù)源"，負(fù)責(zé)從請(qǐng)求上下文和異常對(duì)象中提取標(biāo)準(zhǔn)化信息。默認(rèn)實(shí)現(xiàn)DefaultErrorAttributes會(huì)提取以下核心字段：
timestamp：錯(cuò)誤發(fā)生時(shí)間戳status：HTTP狀態(tài)碼error：HTTP錯(cuò)誤原因短語(yǔ)message：異常消息path：請(qǐng)求路徑
擴(kuò)展實(shí)現(xiàn)技巧：通過(guò)重寫getErrorAttributes方法添加業(yè)務(wù)字段
@Component
public class EnhancedErrorAttributes extends DefaultErrorAttributes {
@Override
public Map<String, Object> getErrorAttributes(WebRequest webRequest, ErrorAttributeOptions options) {
Map<String, Object> attributes = super.getErrorAttributes(webRequest, options);
// 添加應(yīng)用標(biāo)識(shí)
attributes.put("appId", "order-service");
// 添加請(qǐng)求ID（從請(qǐng)求頭獲?。?
attributes.put("requestId", webRequest.getHeader("X-Request-ID"));
// 處理自定義異常
Throwable error = getError(webRequest);
if (error instanceof ValidationException) {
attributes.put("validationErrors", extractValidationErrors((ValidationException) error));
}
return attributes;
}
private List<String> extractValidationErrors(ValidationException e) {
// 提取校驗(yàn)錯(cuò)誤信息的邏輯
}
}
2.2 ErrorViewResolver：錯(cuò)誤頁(yè)面的智能匹配
當(dāng)需要返回HTML響應(yīng)時(shí)，ErrorViewResolver負(fù)責(zé)根據(jù)狀態(tài)碼和異常類型匹配最合適的視圖。其默認(rèn)實(shí)現(xiàn)DefaultErrorViewResolver采用"精確匹配優(yōu)先"的策略：
- 查找
error/404、error/500等狀態(tài)碼對(duì)應(yīng)的視圖； - 查找
error/4xx、error/5xx等狀態(tài)碼段對(duì)應(yīng)的視圖； - 匹配通用
error視圖； - 若均未找到，使用內(nèi)置默認(rèn)視圖。
thymeleaf模板示例（src/main/resources/templates/error/4xx.html）：
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>客戶端錯(cuò)誤</title>
</head>
<body>
<div class="error-container">
<h1 th:text="${status} + ' ' + ${error}">400 Bad Request</h1>
<p th:text="${message}">請(qǐng)求參數(shù)錯(cuò)誤</p>
<p>請(qǐng)求路徑: <span th:text="${path}"></span></p>
<p th:if="${timestamp}">發(fā)生時(shí)間: <span th:text="${#dates.format(timestamp, 'yyyy-MM-dd HH:mm:ss')}"></span></p>
</div>
</body>
</html>
2.3 BasicErrorController：錯(cuò)誤響應(yīng)的調(diào)度中心
BasicErrorController作為/error端點(diǎn)的處理器，是整個(gè)異常處理流程的"調(diào)度中心"。
其核心能力體現(xiàn)在：
- 通過(guò)
@RequestMapping的produces屬性區(qū)分響應(yīng)類型； - 利用
ErrorAttributes獲取錯(cuò)誤信息； - 委托
ErrorViewResolver解析視圖； - 支持通過(guò)配置修改行為（如
server.error.include-message=always控制是否包含異常消息）。
關(guān)鍵配置參數(shù)：
# 錯(cuò)誤頁(yè)面路徑 server.error.path=/error # 是否包含異常堆棧信息（never/always/on_param） server.error.include-stacktrace=on_param # 是否包含消息（never/always/on_param） server.error.include-message=always # 白標(biāo)錯(cuò)誤頁(yè)面是否啟用 server.error.whitelabel.enabled=false
三、實(shí)戰(zhàn)進(jìn)階：構(gòu)建企業(yè)級(jí)異常處理體系
在實(shí)際項(xiàng)目中，需要結(jié)合業(yè)務(wù)特點(diǎn)設(shè)計(jì)完整的異常處理方案，既滿足標(biāo)準(zhǔn)化要求，又能適應(yīng)復(fù)雜的業(yè)務(wù)場(chǎng)景。
3.1 異常體系的標(biāo)準(zhǔn)化設(shè)計(jì)
企業(yè)級(jí)應(yīng)用應(yīng)建立分層的異常體系，示例結(jié)構(gòu)如下：
BaseException（基礎(chǔ)異常） ├─ BusinessException（業(yè)務(wù)異常） │ ├─ OrderException（訂單相關(guān)異常） │ ├─ PaymentException（支付相關(guān)異常） │ └─ UserException（用戶相關(guān)異常） ├─ SystemException（系統(tǒng)異常） │ ├─ DatabaseException（數(shù)據(jù)庫(kù)異常） │ └─ RemoteServiceException（遠(yuǎn)程服務(wù)異常） └─ ValidationException（參數(shù)校驗(yàn)異常）
每個(gè)異常類應(yīng)包含：
- 錯(cuò)誤碼（如
BIZ_ORDER_NOT_FOUND） - 錯(cuò)誤消息
- 嚴(yán)重程度
- 相關(guān)上下文信息
實(shí)現(xiàn)示例：
public class BusinessException extends BaseException {
// 錯(cuò)誤碼
private final String errorCode;
// 相關(guān)業(yè)務(wù)數(shù)據(jù)
private final Map<String, Object> context;
public BusinessException(String errorCode, String message) {
super(message);
this.errorCode = errorCode;
this.context = new HashMap<>();
}
public BusinessException addContext(String key, Object value) {
this.context.put(key, value);
return this;
}
// getter方法
}
3.2 全局異常處理器的最佳實(shí)現(xiàn)
使用@ControllerAdvice實(shí)現(xiàn)全局異常處理時(shí)，應(yīng)遵循"精確匹配優(yōu)先、逐層捕獲"的原則：
@ControllerAdvice
@Slf4j
public class GlobalExceptionHandler {
// 處理參數(shù)校驗(yàn)異常
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ApiError> handleValidationException(MethodArgumentNotValidException e) {
List<String> errors = e.getBindingResult().getFieldErrors().stream()
.map(error -> error.getField() + ": " + error.getDefaultMessage())
.collect(Collectors.toList());
ApiError apiError = new ApiError(
HttpStatus.BAD_REQUEST,
"參數(shù)校驗(yàn)失敗",
"VALIDATION_ERROR",
errors
);
return new ResponseEntity<>(apiError, HttpStatus.BAD_REQUEST);
}
// 處理業(yè)務(wù)異常
@ExceptionHandler(BusinessException.class)
public ResponseEntity<ApiError> handleBusinessException(BusinessException e) {
// 記錄業(yè)務(wù)異常日志（INFO級(jí)別）
log.info("業(yè)務(wù)異常: {} {}", e.getErrorCode(), e.getMessage(), e);
ApiError apiError = new ApiError(
HttpStatus.BAD_REQUEST,
e.getMessage(),
e.getErrorCode(),
e.getContext()
);
return new ResponseEntity<>(apiError, HttpStatus.BAD_REQUEST);
}
// 處理系統(tǒng)異常
@ExceptionHandler(SystemException.class)
public ResponseEntity<ApiError> handleSystemException(SystemException e) {
// 記錄系統(tǒng)異常日志（ERROR級(jí)別）
log.error("系統(tǒng)異常: {}", e.getMessage(), e);
ApiError apiError = new ApiError(
HttpStatus.INTERNAL_SERVER_ERROR,
"系統(tǒng)服務(wù)暫時(shí)不可用，請(qǐng)稍后重試",
e.getErrorCode(),
Collections.emptyMap()
);
return new ResponseEntity<>(apiError, HttpStatus.INTERNAL_SERVER_ERROR);
}
// 統(tǒng)一錯(cuò)誤響應(yīng)體
@Data
public static class ApiError {
private final LocalDateTime timestamp;
private final int status;
private final String error;
private final String message;
private final String code;
private final Object details;
public ApiError(HttpStatus status, String message, String code, Object details) {
this.timestamp = LocalDateTime.now();
this.status = status.value();
this.error = status.getReasonPhrase();
this.message = message;
this.code = code;
this.details = details;
}
}
}
3.3 與默認(rèn)機(jī)制的混合使用策略
在實(shí)際項(xiàng)目中，建議采用"自定義處理器為主，默認(rèn)機(jī)制為輔"的混合策略：
- 所有業(yè)務(wù)異常和已知系統(tǒng)異常，由
@ControllerAdvice處理； - 未捕獲的異常和HTTP狀態(tài)碼錯(cuò)誤（如404、405），由默認(rèn)機(jī)制處理；
- 通過(guò)配置確保JSON響應(yīng)的一致性。
實(shí)現(xiàn)配置：
# 禁用白標(biāo)錯(cuò)誤頁(yè)面 server.error.whitelabel.enabled=false # 自定義錯(cuò)誤屬性 spring.factories=org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ com.example.exception.CustomErrorAttributes # 確保404等錯(cuò)誤拋出異常，由全局處理器處理 spring.mvc.throw-exception-if-no-handler-found=true spring.web.resources.add-mappings=false
同時(shí)，為默認(rèn)機(jī)制創(chuàng)建統(tǒng)一的錯(cuò)誤頁(yè)面和JSON響應(yīng)格式：
- 創(chuàng)建
src/main/resources/templates/error.html作為默認(rèn)錯(cuò)誤頁(yè)面 - 通過(guò)自定義
ErrorAttributes確保JSON響應(yīng)格式與全局處理器一致
四、性能與安全考量
在設(shè)計(jì)異常處理機(jī)制時(shí)，還需關(guān)注性能和安全方面的問(wèn)題：
4.1 異常處理的性能優(yōu)化
- 避免在循環(huán)中拋出異常（異常創(chuàng)建成本高，尤其是堆棧跟蹤）；
- 異常消息避免復(fù)雜字符串拼接；
- 堆棧信息僅在開發(fā)和調(diào)試環(huán)境返回；
- 合理使用異常緩存（對(duì)于頻繁發(fā)生的已知異常）。
4.2 安全加固措施
- 生產(chǎn)環(huán)境隱藏詳細(xì)堆棧信息；
- 對(duì)敏感信息（如數(shù)據(jù)庫(kù)路徑、用戶密碼）進(jìn)行脫敏；
- 限制錯(cuò)誤信息的詳細(xì)程度，避免泄露系統(tǒng)實(shí)現(xiàn)細(xì)節(jié)；
- 對(duì)異常日志進(jìn)行審計(jì)，監(jiān)測(cè)異常模式發(fā)現(xiàn)潛在攻擊。
五、總結(jié)與最佳實(shí)踐
SpringBoot異常處理機(jī)制為開發(fā)者提供了強(qiáng)大的基礎(chǔ)能力，結(jié)合企業(yè)級(jí)實(shí)踐，可總結(jié)出以下最佳實(shí)踐：
- 建立完善的異常體系：按業(yè)務(wù)域和錯(cuò)誤類型劃分異常，便于精準(zhǔn)處理；
- 統(tǒng)一響應(yīng)格式：無(wú)論是自定義處理器還是默認(rèn)機(jī)制，保持錯(cuò)誤響應(yīng)格式一致；
- 精細(xì)化日志策略：不同類型異常采用不同日志級(jí)別，包含足夠上下文信息；
- 環(huán)境差異化處理：開發(fā)環(huán)境提供詳細(xì)調(diào)試信息，生產(chǎn)環(huán)境返回安全友好的提示；
- 定期異常分析：通過(guò)監(jiān)控和日志分析，識(shí)別高頻異常并優(yōu)化處理邏輯。
通過(guò)深入理解SpringBoot異常處理的底層原理，并結(jié)合實(shí)際業(yè)務(wù)場(chǎng)景進(jìn)行合理擴(kuò)展，能夠構(gòu)建出既穩(wěn)定可靠又易于維護(hù)的異常處理體系，為應(yīng)用的健壯性提供堅(jiān)實(shí)保障。
以上為個(gè)人經(jīng)驗(yàn)，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。
相關(guān)文章
使用ScheduledThreadPoolExecutor踩過(guò)最痛的坑
這篇文章主要介紹了使用ScheduledThreadPoolExecutor踩過(guò)最痛的坑及解決方案,具有很好的參考價(jià)值,希望對(duì)大家有所幫助,如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2023-08-08
Java注解詳解及實(shí)現(xiàn)自定義注解的方法
這篇文章主要介紹了Java注解詳解及實(shí)現(xiàn)自定義注解的方法,本文給大家介紹了jdk中預(yù)定義的一些注解及自定義注解的相關(guān)知識(shí)，需要的朋友可以參考下2022-06-06
Elasticsearch算分優(yōu)化方案之rescore_query示例詳解
這篇文章主要為大家介紹了Elasticsearch算分優(yōu)化方案之rescore_query示例詳解,有需要的朋友可以借鑒參考下,希望能夠有所幫助,祝大家多多進(jìn)步,早日升職加薪2023-08-08
下面筆者就為大家分享一篇java整合SSM框架的圖文教程，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。一起跟隨筆者過(guò)來(lái)看看吧2017-11-11
Java Math.round()，Math.ceil()，Math.floor()的區(qū)別詳解
這篇文章主要介紹了Java Math.round()，Math.ceil()，Math.floor()的區(qū)別詳解，文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧2020-08-08
解決spring boot環(huán)境切換失效的問(wèn)題
這篇文章主要介紹了解決spring boot環(huán)境切換失效的問(wèn)題，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2021-09-09
這篇文章主要介紹了Java中的TreeSet集合詳解,TreeSet 是一個(gè) 有序集合,它擴(kuò)展了 AbstractSet 類并實(shí)現(xiàn)了 NavigableSet 接口,作為自平衡二叉搜索樹,二叉樹的每個(gè)節(jié)點(diǎn)包括一個(gè)額外的位,用于識(shí)別紅色或黑色的節(jié)點(diǎn)的顏色,需要的朋友可以參考下2023-09-09
Hibernate分頁(yè)的兩種實(shí)現(xiàn)方法
這篇文章主要介紹了Hibernate分頁(yè)的兩種實(shí)現(xiàn)方法,結(jié)合實(shí)例形式講述了criteria分頁(yè)與hql分頁(yè)的實(shí)現(xiàn)方法,需要的朋友可以參考下2016-03-03
IDEA?下?Gradle?刪除多余無(wú)用依賴的處理方法
這篇文章主要介紹了IDEA下Gradle刪除多余無(wú)用依賴,使用該插件可以一定程度上幫助我們刪除無(wú)用依賴，但是也可能會(huì)多刪除有用的依賴，需要在使用插件自動(dòng)修復(fù)后手動(dòng)檢測(cè)項(xiàng)目，驗(yàn)證是否會(huì)出現(xiàn)問(wèn)題，避免導(dǎo)致上線發(fā)布錯(cuò)誤的負(fù)優(yōu)化2022-03-03
Java如何定位進(jìn)程中占用CPU或內(nèi)存最多的線程
在排查?Java?性能問(wèn)題時(shí),定位占用?CPU?或內(nèi)存最多的線程是關(guān)鍵步驟,本文為大家介紹了針對(duì)兩種場(chǎng)景的具體排查方法,希望對(duì)大家有一定的幫助2025-05-05