SpringBoot統(tǒng)一異常處理的實(shí)用方案
更新時(shí)間：2026年03月25日 09:17:30 作者：希望永不加班
在日常開發(fā)中,你一定見過這樣的代碼：代碼冗余、維護(hù)困難、前端對(duì)接痛苦、日志混亂,線上出問題還難定位,統(tǒng)一異常處理,就是用來解決這些問題的,今天這篇文章,帶你從零到一實(shí)現(xiàn)SpringBoot全局統(tǒng)一異常處理,需要的朋友可以參考下
前言
在日常開發(fā)中，你一定見過這樣的代碼：
try {
// 業(yè)務(wù)邏輯
} catch (Exception e) {
e.printStackTrace();
}或者接口返回五花八門：
- 有的返回
500錯(cuò)誤 - 有的返回一段文字
- 有的直接拋異常前端看不懂
- 每個(gè)接口都寫一遍 try-catch
代碼冗余、維護(hù)困難、前端對(duì)接痛苦、日志混亂，線上出問題還難定位。
統(tǒng)一異常處理，就是用來解決這些問題的。
今天這篇文章，帶你從零到一實(shí)現(xiàn) Spring Boot 全局統(tǒng)一異常處理，
包含：自定義異常、統(tǒng)一返回、全局捕獲、異常分類、日志規(guī)范、實(shí)戰(zhàn)案例。
看完直接落地到你的項(xiàng)目里。
一、為什么要做統(tǒng)一異常處理？
1. 現(xiàn)狀痛點(diǎn)
- 每個(gè)接口都寫 try-catch，代碼重復(fù)
- 異常信息不規(guī)范，前端無法統(tǒng)一解析
- 錯(cuò)誤信息暴露給用戶，不安全
- 日志混亂，難以排查問題
- 系統(tǒng)穩(wěn)定性差，容易直接崩接口
2. 統(tǒng)一異常處理的好處
- 代碼更優(yōu)雅，業(yè)務(wù)層不用處理異常
- 所有異常統(tǒng)一格式返回
- 異?？杀O(jiān)控、可統(tǒng)計(jì)、可告警
- 安全：不把系統(tǒng)異常暴露給前端
- 提升開發(fā)效率與維護(hù)性
二、實(shí)現(xiàn)統(tǒng)一異常處理的核心組件
Spring Boot 提供兩個(gè)最核心注解：
@RestControllerAdvice：全局捕獲控制器異常@ExceptionHandler：捕獲指定類型異常
配合：
- 統(tǒng)一返回結(jié)果類
- 自定義業(yè)務(wù)異常
- 異常分類
- 日志規(guī)范
就能完成一套企業(yè)級(jí)異常體系。
三、第一步：定義統(tǒng)一返回格式
前端最需要的是固定結(jié)構(gòu)。
創(chuàng)建 Result.java：
import lombok.Data;
@Data
public class Result<T> {
private int code;
private String msg;
private T data;
// 成功
public static <T> Result<T> success(T data) {
Result<T> r = new Result<>();
r.setCode(200);
r.setMsg("success");
r.setData(data);
return r;
}
// 失敗
public static <T> Result<T> fail(int code, String msg) {
Result<T> r = new Result<>();
r.setCode(code);
r.setMsg(msg);
r.setData(null);
return r;
}
}以后所有接口統(tǒng)一返回 Result。
四、第二步：自定義業(yè)務(wù)異常
系統(tǒng)異常和業(yè)務(wù)異常要分開。
創(chuàng)建 BusinessException.java：
public class BusinessException extends RuntimeException {
private int code;
private String msg;
public BusinessException(String msg) {
super(msg);
this.code = 500;
this.msg = msg;
}
public BusinessException(int code, String msg) {
super(msg);
this.code = code;
this.msg = msg;
}
// getter
}使用示例：
if (user == null) {
throw new BusinessException(400, "用戶不存在");
}五、第三步：定義全局異常捕獲類（核心）
創(chuàng)建 GlobalExceptionHandler.java：
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {
/**
* 捕獲業(yè)務(wù)異常
*/
@ExceptionHandler(BusinessException.class)
public Result<?> handleBusinessException(BusinessException e) {
log.warn("業(yè)務(wù)異常：{}", e.getMsg());
return Result.fail(e.getCode(), e.getMsg());
}
/**
* 捕獲參數(shù)校驗(yàn)異常
*/
@ExceptionHandler(IllegalArgumentException.class)
public Result<?> handleIllegalArgument(IllegalArgumentException e) {
log.warn("參數(shù)異常：{}", e.getMessage());
return Result.fail(400, e.getMessage());
}
/**
* 捕獲空指針
*/
@ExceptionHandler(NullPointerException.class)
public Result<?> handleNullPointer(NullPointerException e) {
log.error("空指針異常", e);
return Result.fail(500, "服務(wù)器內(nèi)部錯(cuò)誤");
}
/**
* 兜底：所有其他異常
*/
@ExceptionHandler(Exception.class)
public Result<?> handleException(Exception e) {
log.error("系統(tǒng)異常", e);
return Result.fail(500, "服務(wù)器繁忙，請(qǐng)稍后再試");
}
}作用：
所有 Controller 拋出的異常，都會(huì)進(jìn)入這里統(tǒng)一處理。
六、第四步：整合 Validation 參數(shù)校驗(yàn)（非常實(shí)用）
前端傳參錯(cuò)誤，統(tǒng)一返回。
1. 引入依賴
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>2. DTO 加校驗(yàn)
import jakarta.validation.constraints.NotBlank;
public class UserLoginDTO {
@NotBlank(message = "用戶名不能為空")
private String username;
@NotBlank(message = "密碼不能為空")
private String password;
}3. 接口加@Valid
@PostMapping("/login")
public Result<?> login(@Valid @RequestBody UserLoginDTO dto) {
return Result.success("login success");
}4. 捕獲校驗(yàn)異常
import org.springframework.validation.BindException;
import org.springframework.validation.FieldError;
@ExceptionHandler(BindException.class)
public Result<?> handleBindException(BindException e) {
FieldError fieldError = e.getFieldError();
String msg = fieldError.getDefaultMessage();
log.warn("參數(shù)校驗(yàn)失?。簕}", msg);
return Result.fail(400, msg);
}效果：
前端收到干凈的：
{
"code": 400,
"msg": "用戶名不能為空",
"data": null
}七、第五步：規(guī)范日志級(jí)別（線上必備）
- 業(yè)務(wù)異常：warn
- 參數(shù)異常：warn
- 系統(tǒng)異常：error
示例：
log.warn("業(yè)務(wù)異常：{}", e.getMsg());
log.error("空指針異常", e);便于日志平臺(tái)篩選、告警。
八、第六步：實(shí)際業(yè)務(wù)中怎么用？（最真實(shí)示例）
Service 層：
@Service
public class UserService {
public User login(String username, String password) {
User user = userMapper.selectByUsername(username);
if (user == null) {
throw new BusinessException(400, "用戶名或密碼錯(cuò)誤");
}
if (!user.getPassword().equals(password)) {
throw new BusinessException(400, "用戶名或密碼錯(cuò)誤");
}
return user;
}
}Controller 層：
@PostMapping("/login")
public Result<User> login(@Valid @RequestBody UserLoginDTO dto) {
User user = userService.login(dto.getUsername(), dto.getPassword());
return Result.success(user);
}沒有 try-catch！
代碼極度清爽。
九、企業(yè)級(jí)異常分類規(guī)范
你可以直接在項(xiàng)目里使用這套異常碼：
- 200 成功
- 400 參數(shù)錯(cuò)誤
- 401 未登錄
- 403 無權(quán)限
- 404 不存在
- 500 系統(tǒng)錯(cuò)誤
- 1001~1999 業(yè)務(wù)自定義
示例：
throw new BusinessException(401, "請(qǐng)先登錄"); throw new BusinessException(403, "無此權(quán)限"); throw new BusinessException(1001, "余額不足");
以上就是SpringBoot統(tǒng)一異常處理的實(shí)用方案的詳細(xì)內(nèi)容，更多關(guān)于SpringBoot統(tǒng)一異常處理的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！
相關(guān)文章
Java?網(wǎng)絡(luò)編程TCP、UDP、HTTP、WebSocket全解
文章主要講解了Java網(wǎng)絡(luò)編程的核心概念及實(shí)現(xiàn)方法,涵蓋了TCP和UDP傳輸層協(xié)議、HTTP和WebSocket應(yīng)用層協(xié)議,以及生產(chǎn)環(huán)境中最佳實(shí)踐,感興趣的朋友跟隨小編一起看看吧2026-04-04
這篇文章主要介紹了mybatis plus in方法使用說明，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。一起跟隨小編過來看看吧2020-11-11
這篇文章主要介紹了Java無法輸出中文問題及解決方案，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2022-12-12
利用java實(shí)現(xiàn)中獎(jiǎng)概率詳情
這篇文章主要介紹了利用java實(shí)現(xiàn)中獎(jiǎng)概率詳情，根據(jù)概率將獎(jiǎng)品劃分區(qū)間，每個(gè)區(qū)間代表一個(gè)獎(jiǎng)品，然后抽取???隨機(jī)數(shù)??，反查落在那個(gè)區(qū)間上，即為所抽取的獎(jiǎng)品，需要的朋友可以參考一下2022-07-07
Java數(shù)據(jù)結(jié)構(gòu)之順序表和鏈表精解
我在學(xué)習(xí)完順序表后一直對(duì)順序表和鏈表的概念存在一些疑問，這里給出一些分析和看法，通讀本篇對(duì)大家的學(xué)習(xí)或工作具有一定的價(jià)值，需要的朋友可以參考下2021-09-09
SpringBoot內(nèi)部調(diào)用事務(wù)不起作用問題的解決方案
這篇文章主要介紹了SpringBoot事務(wù)不起作用問題的解決方案,文中通過示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2019-10-10
這篇文章主要介紹了通過Java實(shí)現(xiàn)bash命令過程解析,文中通過示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2020-01-01
這篇文章主要介紹了JVM創(chuàng)建對(duì)象及訪問定位過程詳解,文中通過示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2020-12-12
本文介紹了如何在Jenkins 2.332.3版本中安裝插件、配置全局安全、創(chuàng)建和分配角色,以實(shí)現(xiàn)用戶權(quán)限管理2026-01-01
SpringBoot集成Nacos實(shí)現(xiàn)注冊(cè)中心與配置中心流程詳解
這篇文章主要介紹了SpringBoot集成Nacos實(shí)現(xiàn)注冊(cè)中心與配置中心流程，文中通過示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來一起學(xué)習(xí)吧2023-02-02