Spring Boot 異常處理

1. 前言

程序中出現異常是普遍現象， Java 程序員想必早已習慣，根據控制臺輸出的異常信息，分析異常產生的原因，然后進行針對性處理的過程。

Spring Boot 項目中，數據持久層、服務層到控制器層都可能拋出異常。如果我們在各層都進行異常處理，程序代碼會顯得支離破碎，難以理解。

實際上，異常可以從內層向外層不斷拋出，最后在控制器層進行統一處理。 Spring Boot 提供了全局性的異常處理機制，本節我們就分別演示下，默認情況、控制器返回視圖、控制器返回 JSON 數據三種情況的異常處理方法。

2. Spring Boot 默認異常處理機制

Spring Boot 開發的 Web 項目具備默認的異常處理機制，無須編寫異常處理相關代碼，即可提供默認異常機制，下面具體演示下。

2.1 使用 Spring Initializr 創建項目

Spring Boot 版本選擇 2.2.5 ，Group 為 com.imooc ， Artifact 為 spring-boot-exception-default ，生成項目后導入 Eclipse 開發環境。

2.2 引入項目依賴

引入 Web 項目依賴即可。

實例：

		<!-- web項目依賴 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

2.3 Spring Boot 默認異常處理

我們在啟動項目， Spring Boot Web 項目默認啟動端口為 8080 ，所以直接訪問 http://127.0.0.1:8080 ，顯示如下：

如上圖所示，Spring Boot 默認的異常處理機制生效，當出現異常時會自動轉向 /error 路徑。

3. 控制器返回視圖時的異常處理

在使用模板引擎開發 Spring Boot Web 項目時，控制器會返回視圖頁面。我們使用 Thymeleaf 演示控制器返回視圖時的異常處理方式，其他模板引擎處理方式也是相似的。

3.1 使用 Spring Initializr 創建項目

Spring Boot 版本選擇 2.2.5 ，Group 為 com.imooc ， Artifact 為 spring-boot-exception-controller，生成項目后導入 Eclipse 開發環境。

3.2 引入項目依賴

引入 Web 項目依賴、熱部署依賴。此處使用 Thymeleaf 演示控制器返回視圖時的異常處理方式，所以引入 Thymeleaf 依賴。

實例：

		<!-- web項目依賴 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<!-- 熱部署 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
		</dependency>
		<!-- ThymeLeaf依賴 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-thymeleaf</artifactId>
		</dependency>

3.3 定義異常類

在異常處理之前，我們應該根據業務場景具體情況，定義一系列的異常類，習慣性的還會為各種異常分配錯誤碼，如下圖為支付寶開放平臺的公共錯誤碼信息。

本節我們為了演示，簡單的定義 2 個異常類，包含錯誤碼及錯誤提示信息。

實例：

/**
 * 自定義異常
 */
public class BaseException extends Exception {
	/**
	 * 錯誤碼
	 */
	private int code;
	/**
	 * 錯誤提示信息
	 */
	private String msg;

	public BaseException(int code, String msg) {
		super();
		this.code = code;
		this.msg = msg;
	}
	// 省略get set
}

實例：

/**
 * 密碼錯誤異常
 */
public class PasswordException extends BaseException {
	public PasswordException() {
		super(10001, "密碼錯誤");
	}
}

實例：

/**
 * 驗證碼錯誤異常
 */
public class VerificationCodeException extends BaseException {
	public VerificationCodeException() {
		super(10002, "驗證碼錯誤");
	}
}

3.4 控制器拋出異常

定義控制器 GoodsController ，然后使用注解 @Controller 標注該類，類中方法的返回值即為視圖文件名。

在 GoodsController 類定義 4 個方法，分別用于正常訪問、拋出密碼錯誤異常、拋出驗證碼錯誤異常、拋出未自定義的異常，代碼如下。

實例：

/**
 * 商品控制器
 */
@Controller
public class GoodsController {
	/**
	 * 正常方法
	 */
	@RequestMapping("/goods")
	public String goods() {
		return "goods";// 跳轉到resource/templates/goods.html頁面
	}

	/**
	 * 拋出密碼錯誤異常的方法
	 */
	@RequestMapping("/checkPassword")
	public String checkPassword() throws PasswordException {
		if (true) {
			throw new PasswordException();// 模擬拋出異常，便于測試
		}
		return "goods";
	}

	/**
	 * 拋出驗證碼錯誤異常的方法
	 */
	@RequestMapping("/checkVerification")
	public String checkVerification() throws VerificationCodeException {
		if (true) {
			throw new VerificationCodeException();// 模擬拋出異常，便于測試
		}
		return "goods";
	}

	/**
	 * 拋出未自定義的異常
	 */
	@RequestMapping("/other")
	public String other() throws Exception {
		int a = 1 / 0;// 模擬異常
		return "goods";
	}
}

3.5 開發基于 @ControllerAdvice 的全局異常類

@ControllerAdvice 注解標注的類可以處理 @Controller 標注的控制器類拋出的異常，然后進行統一處理。

實例：

/**
 * 控制器異常處理類
 */
@ControllerAdvice(annotations = Controller.class) // 全局異常處理
public class ControllerExceptionHandler {
	@ExceptionHandler({ BaseException.class }) // 當發生BaseException類(及其子類)的異常時，進入該方法
	public ModelAndView baseExceptionHandler(BaseException e) {
		ModelAndView mv = new ModelAndView();
		mv.addObject("code", e.getCode());
		mv.addObject("message", e.getMessage());
		mv.setViewName("myerror");// 跳轉到resource/templates/myerror.html頁面
		return mv;
	}

	@ExceptionHandler({ Exception.class }) // 當發生Exception類的異常時，進入該方法
	public ModelAndView exceptionHandler(Exception e) {
		ModelAndView mv = new ModelAndView();
		mv.addObject("code", 99999);// 其他異常統一編碼為99999
		mv.addObject("message", e.getMessage());
		mv.setViewName("myerror");// 跳轉到resource/templates/myerror.html頁面
		return mv;
	}
}

按照 ControllerExceptionHandler 類的處理邏輯，當發生 BaseException 類型的異常時，會跳轉到 myerror.html 頁面，并顯示相應的錯誤碼和錯誤信息；當發生其他類型的異常時，錯誤碼為 99999 ，錯誤信息為相關的異常信息。

3.6 開發前端頁面

在 resource/templates 下分別新建 goods.html 和 myerror.html 頁面，作為正常訪問及發生異常時跳轉的視圖頁面。

實例：

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>goods.html頁面</title>
</head>
<body>
	<div>商品信息頁面</div>
</body>
</html>

實例：

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>myerror.html頁面</title>
</head>
<body>
	錯誤碼：
	<span th:text="${code}"></span> 
	錯誤信息：
	<span th:text="${message}"></span>
</body>
</html>

3.7 測試

啟動項目，分別訪問控制器中的 4 個方法，結果如下：

可見，當控制器方法拋出異常時，會按照全局異常類設定的邏輯統一處理。

4. 控制器返回 JSON 數據時的異常處理

在控制器類上添加 @RestController 注解，控制器方法處理完畢后會返回 JSON 格式的數據。

此時，可以使用 @RestControllerAdvice 注解標注的類 ，來捕獲 @RestController 標注的控制器拋出的異常。

4.1 使用 Spring Initializr 創建項目

Spring Boot 版本選擇 2.2.5 ，Group 為 com.imooc ， Artifact 為 spring-boot-exception-restcontroller，生成項目后導入 Eclipse 開發環境。

4.2 引入項目依賴

引入 Web 項目依賴、熱部署依賴即可。

實例：

		<!-- web項目依賴 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<!-- 熱部署 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
		</dependency>

4.3 定義異常類

還是使用上文中定義的異常類即可。

4.4 統一控制器返回數據格式

這時候，我們就需要思考一個問題了。前端請求后端控制器接口后，怎么區分后端接口是正常返回結果，還是發生了異常？

不論后端接口是正常執行，還是中間發生了異常，最好給前端返回統一的數據格式，便于前端統一分析處理。

OK，此時我們就可以封裝后端接口返回的業務邏輯對象 ResultBo ，代碼如下：

實例：

/**
 * 后端接口返回的統一業務邏輯對象
 */
public class ResultBo<T> {

	/**
	 * 錯誤碼 0表示沒有錯誤(異常) 其他數字代表具體錯誤碼
	 */
	private int code;
	/**
	 * 后端返回消息
	 */
	private String msg;
	/**
	 * 后端返回的數據
	 */
	private T data;

	/**
	 * 無參數構造函數
	 */
	public ResultBo() {
		this.code = 0;
		this.msg = "操作成功";
	}

	/**
	 * 帶數據data構造函數
	 */
	public ResultBo(T data) {
		this();
		this.data = data;
	}

	/**
	 * 存在異常的構造函數
	 */
	public ResultBo(Exception ex) {
		if (ex instanceof BaseException) {
			this.code = ((BaseException) ex).getCode();
			this.msg = ex.getMessage();
		} else {
			this.code = 99999;// 其他未定義異常
			this.msg = ex.getMessage();
		}
	}
	// 省略 get set
}

4.5 控制器拋出異常

定義控制器 RestGoodsController ，并使用 @RestController 注解標注。在其中定義 4 個方法，然后分別用于正常訪問、拋出密碼錯誤異常、拋出驗證碼錯誤異常，以及拋出不屬于自定義異常類的異常。

實例：

/**
 * Rest商品控制器
 */
@RestController
public class RestGoodsController {
	/**
	 * 正常方法
	 */
	@RequestMapping("/goods")
	public ResultBo goods() {
		return new ResultBo<>(new ArrayList());// 正常情況下應該返回商品列表
	}

	/**
	 * 拋出密碼錯誤異常的方法
	 */
	@RequestMapping("/checkPassword")
	public ResultBo checkPassword() throws PasswordException {
		if (true) {
			throw new PasswordException();// 模擬拋出異常，便于測試
		}
		return new ResultBo<>(true);// 正常情況下應該返回檢查密碼的結果true或false
	}

	/**
	 * 拋出驗證碼錯誤異常的方法
	 */
	@RequestMapping("/checkVerification")
	public ResultBo checkVerification() throws VerificationCodeException {
		if (true) {
			throw new VerificationCodeException();// 模擬拋出異常，便于測試
		}
		return new ResultBo<>(true);// 正常情況下應該返回檢查驗證碼的結果true或false
	}

	/**
	 * 拋出未自定義的異常
	 */
	@RequestMapping("/other")
	public ResultBo other() throws Exception {
		int a = 1 / 0;// 模擬異常
		return new ResultBo<>(true);
	}
}

4.6 開發基于 @RestControllerAdvice 的全局異常類

@RestControllerAdvice 注解標注的類可以處理 RestController 控制器類拋出的異常，然后進行統一處理。

實例：

/**
 * Rest控制器異常處理類
 */
@RestControllerAdvice(annotations = RestController.class) // 全局異常處理
public class RestControllerExceptionHandler {
	/**
	 * 處理BaseException類(及其子類)的異常
	 */
	@ExceptionHandler({ BaseException.class })
	public ResultBo baseExceptionHandler(BaseException e) {
		return new ResultBo(e);
	}

	/**
	 * 處理Exception類的異常
	 */
	@ExceptionHandler({ Exception.class })
	public ResultBo exceptionHandler(Exception e) {
		return new ResultBo(e);
	}
}

4.7 測試

啟動項目，分別嘗試訪問控制器中的 4 個接口，結果如下。

5. 小結

Spring Boot 的默認異常處理機制，實際上只能做到提醒開發者 “這個后端接口不存在” 的作用，作用非常有限。

所以我們在開發 Spring Boot 項目時，需要根據項目的實際情況，定義各類異常，并站在全局的角度統一處理異常。

不管項目有多少層次，所有異常都可以向外拋出，直到控制器層進行集中處理。

• 對于返回視圖的控制器，如果沒發生異常就跳轉正常頁面，如果發生異?？梢宰远x錯誤信息頁面。
• 對于返回 JSON 數據的控制器，最好是定義統一的數據返回格式，便于前端根據返回信息進行正?；蛘弋惓Ｇ闆r的處理。