SpringBoot使用spring-boot-starter-validation實現(xiàn)參數(shù)校驗
前言
在開發(fā) RESTful 接口時，接口參數(shù)校驗是保障系統(tǒng)健壯性和安全性的重要一環(huán)。Spring Boot 提供了對 Bean Validation 的開箱即用支持 —— 通過 spring-boot-starter-validation 模塊，我們可以非常方便地使用 JSR-380 標(biāo)準(zhǔn)定義的注解（如 @NotNull、@NotBlank、@Email 等）進(jìn)行參數(shù)校驗。
本文將帶你從零開始掌握如何在 Spring Boot 中使用 spring-boot-starter-validation，并通過多個實際案例演示其強(qiáng)大功能，包括：
- 單個參數(shù)校驗
- 對象嵌套校驗
- 自定義校驗規(guī)則
- 全局異常統(tǒng)一處理
- 多語言錯誤信息支持
無論你是初學(xué)者，還是有一定經(jīng)驗的開發(fā)者，這篇文章都能讓你寫出更規(guī)范、更健壯的接口！
一、什么是 spring-boot-starter-validation
定義
spring-boot-starter-validation 是 Spring Boot 提供的一個 starter 模塊，它默認(rèn)集成了 Hibernate Validator，實現(xiàn)了 Java 的 Bean Validation 規(guī)范（JSR-380），可以用于對 Java Bean 的字段進(jìn)行自動校驗。
特性
| 特性 | 描述 |
|---|---|
| 零配置 | 默認(rèn)集成 Hibernate Validator |
| 注解驅(qū)動 | 支持 @NotNull, @Size, @Email 等豐富注解 |
| 分組校驗 | 可以根據(jù)業(yè)務(wù)場景分組驗證 |
| 異常統(tǒng)一處理 | 結(jié)合 @ControllerAdvice 統(tǒng)一處理校驗失敗 |
| 多語言支持 | 支持國際化錯誤提示 |
二、快速入門：引入與使用
Step 1：添加依賴
如果你創(chuàng)建的是一個標(biāo)準(zhǔn)的 Spring Boot Web 項目，spring-boot-starter-web 已經(jīng)默認(rèn)包含了 spring-boot-starter-validation，無需額外添加。
<!-- 如果你想顯式添加 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
Step 2：定義請求對象并添加校驗注解
import javax.validation.constraints.*;
public class UserRequest {
@NotBlank(message = "用戶名不能為空")
private String username;
@Email(message = "郵箱格式不正確")
private String email;
@Min(value = 18, message = "年齡不能小于18歲")
@Max(value = 120, message = "年齡不能大于120歲")
private int age;
// getters and setters...
}
Step 3：在 Controller 中啟用校驗
在 Controller 方法中，使用 @Valid 注解開啟校驗邏輯，并結(jié)合 @RequestBody 使用。
@RestController
@RequestMapping("/users")
public class UserController {
@PostMapping
public String createUser(@Valid @RequestBody UserRequest request) {
return "用戶提交成功：" + request.toString();
}
}
注意：
@Valid必須寫在方法參數(shù)上；- 如果校驗失敗，會拋出
MethodArgumentNotValidException異常；
三、實戰(zhàn)：全局異常統(tǒng)一處理
為了統(tǒng)一返回錯誤信息，我們可以使用 @ControllerAdvice 來捕獲所有校驗異常。
示例代碼：
@ControllerAdvice
public class GlobalValidationHandler {
@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler(MethodArgumentNotValidException.class)
public Map<String, String> handleValidationExceptions(MethodArgumentNotValidException ex) {
Map<String, String> errors = new HashMap<>();
ex.getBindingResult().getAllErrors().forEach((error) -> {
String fieldName = ((org.springframework.validation.FieldError) error).getField();
String errorMessage = error.getDefaultMessage();
errors.put(fieldName, errorMessage);
});
return errors;
}
}
返回示例：
{
"username": "用戶名不能為空",
"email": "郵箱格式不正確"
}
四、高級用法詳解
1. 嵌套對象校驗
你可以對嵌套的對象也進(jìn)行校驗：
public class AddressRequest {
@NotBlank(message = "地址不能為空")
private String detail;
// getter/setter
}
public class UserRequest {
@NotBlank(message = "用戶名不能為空")
private String username;
@NotNull(message = "地址信息不能為空")
private AddressRequest address;
// getter/setter
}
只要加上 @Valid 注解，Spring 會自動遞歸校驗嵌套對象。
2. 分組校驗（Group Validation）
有時候你希望同一個對象在不同接口中使用不同的校驗規(guī)則？這時就可以使用分組校驗。
第一步：定義分組接口
public interface OnCreate {}
public interface OnUpdate {}
第二步：在實體類中指定分組
public class UserRequest {
@NotBlank(groups = OnCreate.class, message = "創(chuàng)建時用戶名不能為空")
@NotBlank(groups = OnUpdate.class, message = "更新時用戶名不能為空")
private String username;
@NotBlank(groups = OnCreate.class, message = "郵箱不能為空")
private String email;
}
第三步：在 Controller 中指定分組
@PostMapping("/create")
public String createUser(@Validated(OnCreate.class) @RequestBody UserRequest request) {
return "創(chuàng)建用戶";
}
@PostMapping("/update")
public String updateUser(@Validated(OnUpdate.class) @RequestBody UserRequest request) {
return "更新用戶";
}
注意：此時必須使用 @Validated 注解（來自 org.springframework.validation.annotation.Validated），而非 @Valid。
3. 自定義校驗規(guī)則
當(dāng)內(nèi)置注解不能滿足需求時，可以自定義校驗器。
步驟如下：
Step 1：創(chuàng)建注解
@Target({ ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = MobileValidator.class)
public @interface Mobile {
String message() default "手機(jī)號格式不正確";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}
Step 2：實現(xiàn)校驗器
public class MobileValidator implements ConstraintValidator<Mobile, String> {
private static final String MOBILE_REGEX = "^1[3-9]\\d{9}$";
@Override
public boolean isValid(String value, ConstraintValidatorContext context) {
return value != null && value.matches(MOBILE_REGEX);
}
}
Step 3：使用注解
@Mobile(message = "手機(jī)號格式錯誤") private String mobile;
五、國際化支持（i18n）
你可以為不同語言提供不同的錯誤提示信息：
在 messages.properties 文件中定義：
NotBlank.userRequest.username=用戶名不能為空 Mobile.userRequest.mobile=手機(jī)號格式錯誤
再配合 Spring 的 MessageSource 和 LocaleResolver，即可實現(xiàn)多語言錯誤提示。
六、常見問題與解決方案
| 問題 | 解決方案 |
|---|---|
| 校驗不生效 | 確保使用 @Valid 或 @Validated |
| 嵌套對象未校驗 | 確保子對象字段也加了注解 |
| 分組無效 | 確保使用 @Validated 并指定分組 |
| 錯誤信息亂碼 | 設(shè)置響應(yīng)編碼或使用 JSON 序列化 |
| 無法獲取字段名 | 使用 FieldError 獲取具體字段 |
七、總結(jié)對比表
| 功能 | 描述 |
|---|---|
| 校驗方式 | 注解驅(qū)動，聲明式校驗 |
| 異常處理 | @ControllerAdvice 統(tǒng)一處理 |
| 嵌套對象 | 支持遞歸校驗 |
| 分組校驗 | 支持按業(yè)務(wù)場景定制 |
| 自定義規(guī)則 | 支持自定義注解和校驗器 |
| 國際化 | 支持多語言提示 |
八、結(jié)語
Spring Boot 提供的 spring-boot-starter-validation 模塊極大簡化了接口參數(shù)校驗的開發(fā)流程，使得我們能夠以最小的成本寫出安全、規(guī)范、可維護(hù)性強(qiáng)的接口代碼。
無論是構(gòu)建企業(yè)級后臺系統(tǒng)，還是搭建高并發(fā) API 平臺，都應(yīng)該合理使用參數(shù)校驗來提升系統(tǒng)的穩(wěn)定性與用戶體驗。
到此這篇關(guān)于SpringBoot使用spring-boot-starter-validation實現(xiàn)參數(shù)校驗的文章就介紹到這了,更多相關(guān)SpringBoot參數(shù)校驗內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
Spring框架原理之實例化bean和@Autowired實現(xiàn)原理方式
這篇文章主要介紹了Spring框架原理之實例化bean和@Autowired實現(xiàn)原理方式,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教2025-05-05
文章主要介紹了SpringSession的“全能序列化”方案,即使用JSON格式替代Java原生序列化來存儲會話數(shù)據(jù),JSON序列化方案能提高系統(tǒng)性能、增強(qiáng)跨語言服務(wù)調(diào)用能力、提升類版本兼容性,并具有更高的安全性,感興趣的朋友跟隨小編一起看看吧2026-04-04
這篇文章主要介紹了一個可以修改圖片分辨率的java工具類，文中的示例代碼講解詳細(xì)，對學(xué)習(xí)JAVA有一定的幫助，感興趣的小伙伴快來跟隨小編一起學(xué)習(xí)吧2021-12-12
Java調(diào)用參數(shù)類型是application/x-www-form-urlencoded的API問題
在使用Postman進(jìn)行接口測試時,對于POST請求,需將請求頭設(shè)置為application/x-www-form-urlencoded,并將參數(shù)轉(zhuǎn)為String類型,通常在GET請求中,參數(shù)直接拼接在URL后,本文通過具體實例,詳細(xì)講解了參數(shù)處理的方法,適合API開發(fā)者參考2024-09-09
今天帶大家復(fù)習(xí)Java基礎(chǔ)知識,文中對Java流程控制作了非常詳細(xì)的介紹及代碼示例,對正在學(xué)習(xí)Java的小伙伴們有很好地幫助,需要的朋友可以參考下2021-05-05
這篇文章主要介紹了SpringBoot統(tǒng)一返回結(jié)果問題，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2023-07-07
這篇文章主要介紹了SpringBoot 單元測試JUnit的使用詳解,文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2019-11-11
這篇文章主要介紹了Java對Excel表格的上傳和下載處理方法,需要的朋友可以參考下2017-08-08
java實現(xiàn)分段讀取文件并通過HTTP上傳的方法
這篇文章主要介紹了java實現(xiàn)分段讀取文件并通過HTTP上傳的方法,實例分析了java分段讀取文件及使用http實現(xiàn)文件傳輸?shù)南嚓P(guān)技巧,具有一定參考借鑒價值,需要的朋友可以參考下2015-07-07
這篇文章主要介紹了IDEA+GIT使用入門詳解,本文通過圖文并茂的形式給大家介紹的非常詳細(xì)，對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值，需要的朋友可以參考下2020-11-11