SpringBoot參數(shù)校驗(yàn)全指南分享
在 Web 開(kāi)發(fā)中，參數(shù)校驗(yàn)是保障接口安全性和數(shù)據(jù)合法性的關(guān)鍵環(huán)節(jié)。
手動(dòng)編寫(xiě)校驗(yàn)邏輯不僅繁瑣，還容易遺漏邊界情況。
Spring Boot 整合了 validation 工具，提供了一套簡(jiǎn)潔高效的參數(shù)校驗(yàn)方案，可快速實(shí)現(xiàn)對(duì)簡(jiǎn)單數(shù)據(jù)類型、對(duì)象類型的校驗(yàn)，并支持自定義異常處理。
一、參數(shù)校驗(yàn)入門(mén)：簡(jiǎn)單數(shù)據(jù)類型校驗(yàn)
1. 引入依賴
Spring Boot 提供了 spring-boot-starter-validation 起步依賴，內(nèi)置了參數(shù)校驗(yàn)所需的核心組件：
<!-- 參數(shù)校驗(yàn)依賴 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>2. 開(kāi)啟參數(shù)校驗(yàn)
在控制器類上添加 @Validated 注解，開(kāi)啟參數(shù)校驗(yàn)功能：
@Validated // 開(kāi)啟參數(shù)校驗(yàn)
@Controller
public class TestController {
// 接口方法...
}
3. 常用校驗(yàn)注解
對(duì)簡(jiǎn)單數(shù)據(jù)類型（如字符串、數(shù)字）的校驗(yàn)，可直接在方法參數(shù)上添加校驗(yàn)注解。
常用注解如下：
| 注解 | 作用 | 示例 |
|---|---|---|
| @NotBlank | 字符串不為 null 且去除空格后不為空串 | @NotBlank String username |
| @NotNull | 對(duì)象不為 null（適用于包裝類） | @NotNull Integer age |
| @NotEmpty | 集合不為 null 且不為空 | @NotEmpty List<String> ids |
| @Min | 數(shù)字最小值 | @Min(0) Integer score |
| @Max | 數(shù)字最大值 | @Max(150) Integer age |
| 字符串符合郵箱格式 | @Email String email | |
| @Length | 字符串長(zhǎng)度在指定范圍內(nèi) | @Length(min=2, max=10) String name |
4. 簡(jiǎn)單類型校驗(yàn)示例
@Validated
@Controller
public class TestController {
@RequestMapping("/user")
@ResponseBody
public String addUser(
@NotBlank(message = "用戶名不能為空") String username, // 非空校驗(yàn)
@NotNull(message = "年齡不能為空") @Min(0) @Max(150) Integer age, // 非空+范圍校驗(yàn)
@Email(message = "郵箱格式不正確") String email // 格式校驗(yàn)
) {
return "參數(shù)校驗(yàn)通過(guò)：" + username + ", " + age + ", " + email;
}
}
message屬性用于自定義校驗(yàn)失敗時(shí)的提示信息。- 當(dāng)參數(shù)不符合校驗(yàn)規(guī)則時(shí)，會(huì)拋出
ConstraintViolationException異常。
二、異常處理：統(tǒng)一響應(yīng)錯(cuò)誤信息
參數(shù)校驗(yàn)失敗后，Spring Boot 會(huì)默認(rèn)拋出異常并返回 400 錯(cuò)誤，但默認(rèn)的錯(cuò)誤信息不夠友好。我們可以通過(guò)以下兩種方式統(tǒng)一處理校驗(yàn)異常：
1. 自定義錯(cuò)誤頁(yè)面（適用于前后端不分離）
Spring Boot 會(huì)自動(dòng)跳轉(zhuǎn)至 src/main/resources/templates/error.html 頁(yè)面，可在該頁(yè)面展示友好的錯(cuò)誤提示：
<!-- error.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>錯(cuò)誤提示</title>
</head>
<body>
<h1>參數(shù)錯(cuò)誤</h1>
<p>請(qǐng)檢查輸入的參數(shù)是否符合要求</p>
</body>
</html>2. 全局異常處理器（適用于前后端分離）
通過(guò) @ControllerAdvice 定義全局異常處理器，捕獲校驗(yàn)異常并返回 JSON 格式的錯(cuò)誤信息：
@ControllerAdvice
@ResponseBody
public class GlobalExceptionHandler {
// 處理簡(jiǎn)單類型參數(shù)校驗(yàn)異常
@ExceptionHandler(ConstraintViolationException.class)
public Map<String, String> handleConstraintViolationException(ConstraintViolationException e) {
Map<String, String> errorMap = new HashMap<>();
// 獲取所有校驗(yàn)失敗的信息
e.getConstraintViolations().forEach(violation -> {
String field = violation.getPropertyPath().toString(); // 參數(shù)名
String message = violation.getMessage(); // 錯(cuò)誤信息
errorMap.put(field, message);
});
return errorMap;
}
}
當(dāng)參數(shù)校驗(yàn)失敗時(shí)，會(huì)返回類似以下的 JSON 響應(yīng)：
{
"username": "用戶名不能為空",
"email": "郵箱格式不正確"
}
三、對(duì)象類型參數(shù)校驗(yàn)
對(duì)于復(fù)雜業(yè)務(wù)場(chǎng)景，接口通常接收對(duì)象類型的參數(shù)（如用戶注冊(cè)信息、訂單信息）。
此時(shí)需對(duì)對(duì)象的每個(gè)屬性進(jìn)行校驗(yàn)，步驟如下：
1. 定義實(shí)體類并添加校驗(yàn)注解
在實(shí)體類的字段上添加校驗(yàn)注解，指定校驗(yàn)規(guī)則和錯(cuò)誤提示：
public class User {
@NotNull(message = "ID不能為空")
private Integer id;
@NotBlank(message = "姓名不能為空")
@Length(min = 2, max = 10, message = "姓名長(zhǎng)度必須在2-10之間")
private String name;
@NotNull(message = "年齡不能為空")
@Min(value = 0, message = "年齡不能為負(fù)數(shù)")
@Max(value = 150, message = "年齡不能超過(guò)150")
private Integer age;
// getter + setter（必須存在，否則校驗(yàn)不生效）
}
2. 在控制器中校驗(yàn)對(duì)象
在控制器方法的對(duì)象參數(shù)前添加 @Validated 注解，并通過(guò) BindingResult 捕獲校驗(yàn)結(jié)果：
@Controller
public class UserController {
@RequestMapping("/addUser")
@ResponseBody
public String addUser(
@Validated User user, // 開(kāi)啟對(duì)象校驗(yàn)
BindingResult result // 用于接收校驗(yàn)結(jié)果
) {
// 判斷是否有校驗(yàn)失敗
if (result.hasErrors()) {
// 收集所有錯(cuò)誤信息
StringBuilder errorMsg = new StringBuilder();
result.getAllErrors().forEach(error -> {
FieldError fieldError = (FieldError) error;
errorMsg.append(fieldError.getField()).append(":").append(fieldError.getDefaultMessage()).append("; ");
});
return "參數(shù)錯(cuò)誤：" + errorMsg.toString();
}
// 校驗(yàn)通過(guò)，處理業(yè)務(wù)邏輯
return "用戶添加成功：" + user.getName();
}
}
@Validated用于開(kāi)啟對(duì)象的屬性校驗(yàn)。BindingResult必須緊跟在被校驗(yàn)對(duì)象之后，用于接收校驗(yàn)結(jié)果，避免異常直接拋出。
四、常見(jiàn)問(wèn)題與最佳實(shí)踐
1. 校驗(yàn)注解不生效？
- 確保已添加
spring-boot-starter-validation依賴。 - 控制器類上是否添加
@Validated注解（簡(jiǎn)單類型校驗(yàn)必需）。 - 對(duì)象類型校驗(yàn)時(shí)，是否在參數(shù)前添加
@Validated注解，且實(shí)體類有 getter/setter 方法。
2. 如何自定義校驗(yàn)規(guī)則？
除了內(nèi)置注解，還可通過(guò) @Pattern 注解自定義正則校驗(yàn)，例如校驗(yàn)手機(jī)號(hào)：
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手機(jī)號(hào)格式不正確")
private String phone;
3. 全局異常處理器的優(yōu)勢(shì)
使用 @ControllerAdvice 定義全局異常處理器，可統(tǒng)一處理所有校驗(yàn)異常，避免在每個(gè)接口中重復(fù)編寫(xiě)錯(cuò)誤處理邏輯，提高代碼復(fù)用性。
總結(jié)
Spring Boot 的參數(shù)校驗(yàn)機(jī)制通過(guò)注解化的方式，極大簡(jiǎn)化了數(shù)據(jù)合法性校驗(yàn)的實(shí)現(xiàn)。
本文介紹了簡(jiǎn)單類型、對(duì)象類型的校驗(yàn)方法，以及異常處理方案，涵蓋了從基礎(chǔ)到實(shí)戰(zhàn)的核心場(chǎng)景。合理使用參數(shù)校驗(yàn)，不僅能減少手動(dòng)校驗(yàn)代碼，還能提高接口的健壯性和安全性。
以上為個(gè)人經(jīng)驗(yàn)，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。
相關(guān)文章
SpringBoot模擬實(shí)現(xiàn)流式輸出效果
這篇文章主要為大家詳細(xì)介紹了如何使用SpringBoot模擬實(shí)現(xiàn)流式輸出效果,并在前端使用流式接收數(shù)據(jù)并打印,感興趣的小伙伴可以參考一下2025-03-03
Java使用條件語(yǔ)句和循環(huán)結(jié)構(gòu)確定控制流(實(shí)例)
下面小編就為大家?guī)?lái)一篇Java使用條件語(yǔ)句和循環(huán)結(jié)構(gòu)確定控制流(實(shí)例)。小編覺(jué)得挺不錯(cuò)的，現(xiàn)在就分享給大家，也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2017-06-06
SpringBoot 接口獲取參數(shù)的注解非常豐富,這篇文章主要為大家詳細(xì)介紹了一些常用參數(shù)注解的使用,文中的示例代碼講解詳細(xì),感興趣的小伙伴可以了解下2026-01-01
JavaWeb實(shí)戰(zhàn)之用Servlet+JDBC實(shí)現(xiàn)用戶登錄與注冊(cè)
這篇文章主要介紹了JavaWeb實(shí)戰(zhàn)之用Servlet+JDBC實(shí)現(xiàn)用戶登錄與注冊(cè),文中有非常詳細(xì)的代碼示例,對(duì)正在學(xué)習(xí)java的小伙伴們有很大的幫助,需要的朋友可以參考下2021-04-04
MultipartResolver實(shí)現(xiàn)文件上傳功能
這篇文章主要為大家詳細(xì)介紹了MultipartResolver實(shí)現(xiàn)文件上傳功能，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2018-06-06
基于Eclipse 的JSP/Servlet的開(kāi)發(fā)環(huán)境的搭建(圖文)
本文將會(huì)詳細(xì)地展示如何搭建JSP的開(kāi)發(fā)環(huán)境。本次教程使用的是最新版的Eclipse 2018-09編輯器和最新版的Apache Tomcat v9.0，步驟詳細(xì)，內(nèi)容詳盡，適合零基礎(chǔ)學(xué)者作為學(xué)習(xí)參考2018-12-12
這篇文章主要介紹了Java同步容器和并發(fā)容器詳解,容器是Java基礎(chǔ)類庫(kù)中使用頻率最高的一部分，Java集合包中提供了大量的容器類來(lái)幫組我們簡(jiǎn)化開(kāi)發(fā),下面小編和大家來(lái)一起學(xué)習(xí)下吧2019-06-06
JAVA Comparator 和 Comparable接口使用方法
本文介紹了Java中Comparable和Comparator接口的使用,包括它們的定義、方法和應(yīng)用場(chǎng)景,Comparable用于定義類的自然排序規(guī)則,而Comparator提供了一種靈活的方式來(lái)定義對(duì)象之間的排序規(guī)則,無(wú)需修改類本身,感興趣的朋友一起看看吧2025-03-03
這篇文章主要為大家詳細(xì)介紹了SpringBoot使用POI進(jìn)行Excel下載，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2019-09-09
這篇文章主要幫助大家輕松掌握java裝飾者模式,具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2016-09-09