在Spring Boot接口開發(fā)中，前端傳參的合法性校驗(yàn)是必不可少的環(huán)節(jié)。此前我們已經(jīng)實(shí)現(xiàn)了接口開發(fā)與全局異常處理的基礎(chǔ)框架，而在實(shí)際開發(fā)中，若直接在接口方法中通過大量if-else判斷參數(shù)是否合法，不僅會(huì)導(dǎo)致代碼冗余、可讀性差，還會(huì)增加后期維護(hù)成本。本文將專門講解如何借助JSR380規(guī)范注解 + 全局異常捕獲，配合自定義校驗(yàn)注解，實(shí)現(xiàn)前端傳參的優(yōu)雅校驗(yàn)，徹底摒棄繁瑣的if-else判斷，讓參數(shù)校驗(yàn)邏輯更簡潔、更規(guī)范、更可復(fù)用。

JSR380是Java EE的參數(shù)校驗(yàn)規(guī)范，定義了一系列用于參數(shù)校驗(yàn)的注解，Spring Boot已默認(rèn)集成相關(guān)實(shí)現(xiàn)（hibernate-validator），無需額外引入過多依賴，即可直接使用注解完成基礎(chǔ)的參數(shù)校驗(yàn)；對(duì)于一些特殊場景（如手機(jī)號(hào)格式、身份證號(hào)校驗(yàn)等），JSR380默認(rèn)注解無法滿足需求，此時(shí)可通過自定義校驗(yàn)注解實(shí)現(xiàn)個(gè)性化校驗(yàn)，再結(jié)合全局異常捕獲，統(tǒng)一處理所有參數(shù)校驗(yàn)失敗的異常，實(shí)現(xiàn)校驗(yàn)邏輯與業(yè)務(wù)邏輯的解耦。

一、基礎(chǔ)準(zhǔn)備：引入依賴（極簡配置）

Spring Boot 2.3及以上版本，已默認(rèn)集成hibernate-validator（JSR380的實(shí)現(xiàn)），若項(xiàng)目為低版本，需手動(dòng)引入以下依賴，確保注解能夠正常生效。依賴配置簡潔，無需額外配置其他參數(shù)，引入后即可直接使用JSR380相關(guān)校驗(yàn)注解。

<!-- JSR380 參數(shù)校驗(yàn)核心依賴（低版本Spring Boot需手動(dòng)引入） -->
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.2.5.Final</version>
</dependency>
<!-- 可選：validation-api 規(guī)范依賴（確保注解識(shí)別） -->
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
</dependency>

注意：高版本Spring Boot（2.3+）無需手動(dòng)引入上述依賴，啟動(dòng)項(xiàng)目后即可直接使用@NotNull、@NotBlank等校驗(yàn)注解；若引入后出現(xiàn)依賴沖突，可排除項(xiàng)目中重復(fù)的validation相關(guān)依賴，確保依賴版本統(tǒng)一。

二、JSR380 核心注解用法（基礎(chǔ)校驗(yàn)，摒棄if-else）

JSR380提供了一系列常用的校驗(yàn)注解，可直接作用于實(shí)體類的字段上，也可直接作用于接口方法的參數(shù)上，用于校驗(yàn)參數(shù)的合法性（如非空、長度、格式等）。使用時(shí)只需在需要校驗(yàn)的字段/參數(shù)上添加對(duì)應(yīng)注解，并指定校驗(yàn)失敗的提示信息，即可完成基礎(chǔ)的參數(shù)校驗(yàn)，無需編寫任何if-else判斷。

以下是開發(fā)中最常用的JSR380注解，結(jié)合實(shí)體類案例詳細(xì)說明用法，所有注解均支持自定義校驗(yàn)失敗提示信息，提升接口返回的友好性。

2.1 常用核心注解說明

• @NotNull：校驗(yàn)參數(shù)不能為null，適用于所有類型（包括基本類型、引用類型），注意：基本類型（如int、long）本身不能為null，因此該注解更適用于引用類型（如String、Integer）。
• @NotBlank：校驗(yàn)字符串不能為null、不能為空字符串（“”）、不能全為空格，僅適用于String類型，是開發(fā)中字符串非空校驗(yàn)的首選注解。
• @NotEmpty：校驗(yàn)集合、數(shù)組、字符串不能為null，且長度不能為0；與@NotBlank的區(qū)別是，@NotEmpty允許字符串為空格（如" "），僅適用于集合、數(shù)組、String類型。
• @Size：校驗(yàn)集合、數(shù)組、字符串的長度，可指定min（最小長度）和max（最大長度），超出范圍則校驗(yàn)失敗。
• @Min：校驗(yàn)數(shù)字（int、long、BigDecimal等）的最小值，小于該值則校驗(yàn)失敗。
• @Max：校驗(yàn)數(shù)字的最大值，大于該值則校驗(yàn)失敗。
• @Email：校驗(yàn)字符串是否符合郵箱格式，默認(rèn)校驗(yàn)規(guī)則較為寬松，可通過regexp屬性自定義郵箱格式正則。
• @Pattern：校驗(yàn)字符串是否符合指定的正則表達(dá)式，適用于自定義格式校驗(yàn)（如手機(jī)號(hào)、身份證號(hào)等，若無需復(fù)用，可直接用該注解替代自定義校驗(yàn)注解）。

2.2 實(shí)體類中使用案例（最常用場景）

在接口開發(fā)中，前端傳參通常會(huì)封裝為實(shí)體類（如用戶注冊(cè)、登錄參數(shù)），將校驗(yàn)注解作用于實(shí)體類字段，配合@Valid注解觸發(fā)校驗(yàn)，即可完成參數(shù)合法性校驗(yàn)，徹底摒棄if-else。

// 示例：用戶注冊(cè)參數(shù)實(shí)體類（所有注解均無導(dǎo)包，直接復(fù)制可用）
@Data
public class UserRegisterDTO {
    // 用戶名：非空、長度2-20位
    @NotBlank(message = "用戶名不能為空")
    @Size(min = 2, max = 20, message = "用戶名長度必須在2-20位之間")
    private String username;
    // 密碼：非空、長度6-16位
    @NotBlank(message = "密碼不能為空")
    @Size(min = 6, max = 16, message = "密碼長度必須在6-16位之間")
    private String password;
    // 郵箱：非空、符合郵箱格式
    @NotBlank(message = "郵箱不能為空")
    @Email(message = "郵箱格式不正確")
    private String email;
    // 年齡：非空、18-60歲之間
    @NotNull(message = "年齡不能為空")
    @Min(value = 18, message = "年齡不能小于18歲")
    @Max(value = 60, message = "年齡不能大于60歲")
    private Integer age;
    // 手機(jī)號(hào)：非空、符合手機(jī)號(hào)正則（此處用@Pattern臨時(shí)實(shí)現(xiàn)，后續(xù)用自定義注解優(yōu)化）
    @NotBlank(message = "手機(jī)號(hào)不能為空")
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手機(jī)號(hào)格式不正確")
    private String phone;
}

2.3 接口中觸發(fā)校驗(yàn)

在接口方法的實(shí)體類參數(shù)前添加**@Valid**注解（或@Validated），即可觸發(fā)該實(shí)體類的參數(shù)校驗(yàn)；若參數(shù)校驗(yàn)失敗，會(huì)拋出MethodArgumentNotValidException異常（請(qǐng)求體參數(shù)校驗(yàn)失?。┗駽onstraintViolationException異常（路徑參數(shù)、請(qǐng)求參數(shù)校驗(yàn)失?。?，后續(xù)通過全局異常捕獲統(tǒng)一處理這些異常，返回友好的提示信息。

// 示例：用戶注冊(cè)接口（觸發(fā)參數(shù)校驗(yàn)）
@RestController
@RequestMapping("/user")
public class UserController {
    // 注冊(cè)接口：@Valid 觸發(fā)UserRegisterDTO的參數(shù)校驗(yàn)
    @PostMapping("/register")
    public Result<Void> register(@Valid @RequestBody UserRegisterDTO registerDTO) {
        // 校驗(yàn)通過后，執(zhí)行注冊(cè)業(yè)務(wù)邏輯（無需任何if-else判斷參數(shù)）
        // 業(yè)務(wù)邏輯...
        return Result.success("注冊(cè)成功");
    }
    // 示例：路徑參數(shù)校驗(yàn)（直接作用于參數(shù)上）
    @GetMapping("/{id}")
    public Result<User> getUserById(@PathVariable @NotNull(message = "用戶ID不能為空") Long id) {
        // 校驗(yàn)通過，執(zhí)行查詢邏輯
        // 業(yè)務(wù)邏輯...
        return Result.success(null);
    }
}

注意：@Valid和@Validated的區(qū)別：@Valid是JSR380規(guī)范提供的注解，支持嵌套校驗(yàn)（如實(shí)體類中包含另一個(gè)實(shí)體類字段，需校驗(yàn)該嵌套字段時(shí)使用）；@Validated是Spring提供的注解，支持分組校驗(yàn)，可根據(jù)不同場景（如新增、修改）執(zhí)行不同的校驗(yàn)規(guī)則，兩者均可觸發(fā)參數(shù)校驗(yàn)，開發(fā)中可根據(jù)需求選擇。

三、全局異常捕獲：統(tǒng)一處理參數(shù)校驗(yàn)錯(cuò)誤

當(dāng)參數(shù)校驗(yàn)失敗時(shí)，Spring Boot會(huì)拋出對(duì)應(yīng)的異常（請(qǐng)求體參數(shù)校驗(yàn)失敗拋出MethodArgumentNotValidException，路徑參數(shù)/請(qǐng)求參數(shù)校驗(yàn)失敗拋出ConstraintViolationException），若不進(jìn)行處理，接口會(huì)返回默認(rèn)的錯(cuò)誤信息，不夠友好且不符合項(xiàng)目統(tǒng)一的響應(yīng)格式。

結(jié)合前文實(shí)現(xiàn)的全局異常處理框架，我們只需新增對(duì)這兩種異常的捕獲，提取校驗(yàn)失敗的提示信息，封裝為統(tǒng)一的響應(yīng)格式（如Result對(duì)象），即可實(shí)現(xiàn)參數(shù)校驗(yàn)錯(cuò)誤的統(tǒng)一處理，無需在每個(gè)接口中單獨(dú)處理校驗(yàn)失敗的情況，進(jìn)一步簡化代碼。

3.1 全局異常處理器新增校驗(yàn)異常捕獲

在全局異常處理器（GlobalExceptionHandler）中，新增兩個(gè)異常處理方法，分別捕獲MethodArgumentNotValidException和ConstraintViolationException，提取校驗(yàn)失敗的提示信息，返回統(tǒng)一的失敗響應(yīng)。

// 全局異常處理器：新增參數(shù)校驗(yàn)異常捕獲（無導(dǎo)包，直接復(fù)制可用）
@RestControllerAdvice
public class GlobalExceptionHandler {
    // 統(tǒng)一響應(yīng)格式（前文已實(shí)現(xiàn)，此處復(fù)用）
    @Data
    public static class Result<T> {
        private Integer code;
        private String message;
        private T data;
        public static <T> Result<T> success(T data) { /* 實(shí)現(xiàn)省略 */ }
        public static <T> Result<T> fail(Integer code, String message) { /* 實(shí)現(xiàn)省略 */ }
    }
    // 1. 捕獲請(qǐng)求體參數(shù)校驗(yàn)失敗異常（@RequestBody + @Valid）
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleMethodArgumentNotValidException(MethodArgumentNotValidException e) {
        // 提取校驗(yàn)失敗的第一條提示信息（也可提取所有提示信息，根據(jù)需求調(diào)整）
        String errorMsg = e.getBindingResult().getFieldErrors().get(0).getDefaultMessage();
        // 返回統(tǒng)一失敗響應(yīng)（狀態(tài)碼400：參數(shù)錯(cuò)誤）
        return Result.fail(400, errorMsg);
    }
    // 2. 捕獲路徑參數(shù)/請(qǐng)求參數(shù)校驗(yàn)失敗異常（@PathVariable/@RequestParam + 校驗(yàn)注解）
    @ExceptionHandler(ConstraintViolationException.class)
    public Result<Void> handleConstraintViolationException(ConstraintViolationException e) {
        // 提取校驗(yàn)失敗的第一條提示信息
        String errorMsg = e.getConstraintViolations().iterator().next().getMessage();
        // 返回統(tǒng)一失敗響應(yīng)
        return Result.fail(400, errorMsg);
    }
    // 其他異常處理方法（前文已實(shí)現(xiàn)，此處省略）
    @ExceptionHandler(Exception.class)
    public Result<Void> handleException(Exception e) { /* 實(shí)現(xiàn)省略 */ }
}

3.2 校驗(yàn)效果演示

當(dāng)前端傳參不符合校驗(yàn)規(guī)則時(shí)，接口會(huì)直接返回統(tǒng)一的失敗響應(yīng)，無需手動(dòng)處理，示例如下：

• 場景1：用戶名為空 → 響應(yīng)：{“code”:400,“message”:“用戶名不能為空”,“data”:null}
• 場景2：密碼長度為3位 → 響應(yīng)：{“code”:400,“message”:“密碼長度必須在6-16位之間”,“data”:null}
• 場景3：手機(jī)號(hào)格式錯(cuò)誤（如12345678901） → 響應(yīng)：{“code”:400,“message”:“手機(jī)號(hào)格式不正確”,“data”:null}

通過這種方式，不僅統(tǒng)一了參數(shù)校驗(yàn)失敗的響應(yīng)格式，還徹底摒棄了接口中的if-else判斷，讓代碼更簡潔、更優(yōu)雅，同時(shí)提升了接口的友好性和可維護(hù)性。

四、自定義校驗(yàn)注解：滿足特殊場景需求

JSR380提供的默認(rèn)注解，只能滿足基礎(chǔ)的參數(shù)校驗(yàn)場景，而在實(shí)際開發(fā)中，經(jīng)常會(huì)遇到一些特殊的校驗(yàn)需求（如手機(jī)號(hào)格式、身份證號(hào)、郵政編碼等），此時(shí)@Pattern注解雖然可以實(shí)現(xiàn)，但正則表達(dá)式分散在各個(gè)字段上，無法復(fù)用，且代碼可讀性差。

通過自定義校驗(yàn)注解，可將特殊的校驗(yàn)邏輯封裝起來，實(shí)現(xiàn)校驗(yàn)邏輯的復(fù)用，同時(shí)讓代碼更簡潔、更規(guī)范。下面以“手機(jī)號(hào)格式校驗(yàn)”為例，詳細(xì)講解自定義校驗(yàn)注解的實(shí)現(xiàn)步驟，其他特殊場景可參考此步驟仿寫。

4.1 步驟1：自定義校驗(yàn)注解（@Phone）

自定義校驗(yàn)注解需添加JSR380規(guī)范的相關(guān)元注解（@Target、@Retention、@Constraint），指定注解的作用范圍、保留策略，以及關(guān)聯(lián)的校驗(yàn)器（Validator），同時(shí)定義校驗(yàn)失敗的提示信息（可自定義）。

// 自定義手機(jī)號(hào)校驗(yàn)注解（@Phone）
@Target({ElementType.FIELD, ElementType.PARAMETER}) // 注解作用范圍：字段、參數(shù)
@Retention(RetentionPolicy.RUNTIME) // 保留策略：運(yùn)行時(shí)生效
@Constraint(validatedBy = PhoneValidator.class) // 關(guān)聯(lián)校驗(yàn)器（核心，實(shí)現(xiàn)校驗(yàn)邏輯）
public @interface Phone {
    // 校驗(yàn)失敗提示信息（默認(rèn)值，可自定義）
    String message() default "手機(jī)號(hào)格式不正確";
    // 分組校驗(yàn)（默認(rèn)分組，可根據(jù)需求擴(kuò)展）
    Class<?>[] groups() default {};
    // 負(fù)載（默認(rèn)，無需修改）
    Class<? extends Payload>[] payload() default {};
}

4.2 步驟2：實(shí)現(xiàn)校驗(yàn)器（PhoneValidator）

校驗(yàn)器需實(shí)現(xiàn)ConstraintValidator接口，重寫initialize（初始化）和isValid（校驗(yàn)邏輯）兩個(gè)方法，其中isValid方法是核心，用于實(shí)現(xiàn)具體的校驗(yàn)邏輯（如手機(jī)號(hào)正則匹配），校驗(yàn)通過返回true，校驗(yàn)失敗返回false。

// 手機(jī)號(hào)校驗(yàn)器（與@Phone注解關(guān)聯(lián)，實(shí)現(xiàn)校驗(yàn)邏輯）
public class PhoneValidator implements ConstraintValidator<Phone, String> {
    // 手機(jī)號(hào)正則表達(dá)式（標(biāo)準(zhǔn)手機(jī)號(hào)格式：13-19開頭，共11位）
    private static final String PHONE_REGEX = "^1[3-9]\\d{9}$";
    /**
     * 初始化方法（可選，用于獲取注解中的參數(shù)，此處無需使用）
     */
    @Override
    public void initialize(Phone constraintAnnotation) {
        ConstraintValidator.super.initialize(constraintAnnotation);
    }
    /**
     * 核心校驗(yàn)邏輯
     * @param value 待校驗(yàn)的參數(shù)（手機(jī)號(hào)字符串）
     * @param context 校驗(yàn)上下文（無需修改）
     * @return true：校驗(yàn)通過，false：校驗(yàn)失敗
     */
    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        // 校驗(yàn)邏輯：非空判斷 + 正則匹配
        if (value == null || value.isEmpty()) {
            // 若需要校驗(yàn)手機(jī)號(hào)非空，可在此處返回false；若允許為空，返回true（結(jié)合@NotBlank使用）
            return false;
        }
        // 正則匹配手機(jī)號(hào)格式
        return value.matches(PHONE_REGEX);
    }
}

4.3 步驟3：使用自定義校驗(yàn)注解

自定義注解實(shí)現(xiàn)完成后，使用方式與JSR380默認(rèn)注解完全一致，直接作用于實(shí)體類字段或接口參數(shù)上，配合@Valid注解觸發(fā)校驗(yàn)，校驗(yàn)失敗后會(huì)被全局異常處理器捕獲，返回自定義的提示信息。

// 示例：修改UserRegisterDTO，使用@Phone注解替代@Pattern
@Data
public class UserRegisterDTO {
    // 其他字段不變...

    // 手機(jī)號(hào)：使用自定義@Phone注解，替代原來的@Pattern，可復(fù)用
    @NotBlank(message = "手機(jī)號(hào)不能為空")
    @Phone(message = "手機(jī)號(hào)格式不正確（請(qǐng)輸入13-19開頭的11位手機(jī)號(hào)）")
    private String phone;
}

注意：自定義校驗(yàn)注解可靈活擴(kuò)展，若需要校驗(yàn)身份證號(hào)、郵政編碼等，只需復(fù)制上述步驟，修改注解名稱、正則表達(dá)式和校驗(yàn)邏輯即可；若校驗(yàn)邏輯復(fù)雜（如校驗(yàn)手機(jī)號(hào)是否已被注冊(cè)），可在isValid方法中注入Service，調(diào)用業(yè)務(wù)邏輯實(shí)現(xiàn)校驗(yàn)（需添加@Component注解，讓校驗(yàn)器被Spring管理）。

五、進(jìn)階優(yōu)化：分組校驗(yàn)（可選，提升靈活性）

在實(shí)際開發(fā)中，同一個(gè)實(shí)體類可能會(huì)用于不同的接口場景（如新增用戶和修改用戶），不同場景的參數(shù)校驗(yàn)規(guī)則可能不同（如新增用戶需要校驗(yàn)用戶名非空，修改用戶可允許用戶名不變）。此時(shí)可通過分組校驗(yàn)，實(shí)現(xiàn)不同場景下的差異化校驗(yàn)，進(jìn)一步提升參數(shù)校驗(yàn)的靈活性。

分組校驗(yàn)的核心是定義分組接口（空接口，無需實(shí)現(xiàn)任何方法），在校驗(yàn)注解中指定分組，在接口中通過@Validated指定需要執(zhí)行的分組，即可實(shí)現(xiàn)差異化校驗(yàn)。示例如下：

// 1. 定義分組接口（空接口，用于區(qū)分不同場景）
public interface AddGroup {} // 新增場景分組
public interface UpdateGroup {} // 修改場景分組

// 2. 實(shí)體類中指定注解的分組
@Data
public class UserDTO {
    // 新增時(shí)校驗(yàn)非空，修改時(shí)無需校驗(yàn)（id由前端傳入，無需校驗(yàn)）
    @NotNull(message = "用戶ID不能為空", groups = AddGroup.class)
    private Long id;

    // 新增和修改時(shí)都需要校驗(yàn)非空和長度
    @NotBlank(message = "用戶名不能為空", groups = {AddGroup.class, UpdateGroup.class})
    @Size(min = 2, max = 20, message = "用戶名長度必須在2-20位之間", groups = {AddGroup.class, UpdateGroup.class})
    private String username;
}

// 3. 接口中指定分組，觸發(fā)對(duì)應(yīng)分組的校驗(yàn)
@RestController
@RequestMapping("/user")
public class UserController {
    // 新增用戶：僅執(zhí)行AddGroup分組的校驗(yàn)
    @PostMapping("/add")
    public Result<Void> add(@Validated(AddGroup.class) @RequestBody UserDTO userDTO) {
        // 業(yè)務(wù)邏輯...
        return Result.success();
    }

    // 修改用戶：僅執(zhí)行UpdateGroup分組的校驗(yàn)
    @PutMapping("/update")
    public Result<Void> update(@Validated(UpdateGroup.class) @RequestBody UserDTO userDTO) {
        // 業(yè)務(wù)邏輯...
        return Result.success();
    }
}

六、總結(jié)

本文通過JSR380規(guī)范注解、全局異常捕獲、自定義校驗(yàn)注解三個(gè)核心環(huán)節(jié)，實(shí)現(xiàn)了Spring Boot前端傳參的優(yōu)雅校驗(yàn)，徹底摒棄了繁瑣的if-else判斷，讓參數(shù)校驗(yàn)邏輯更簡潔、更規(guī)范、更可復(fù)用。

核心要點(diǎn)總結(jié)：1. 基礎(chǔ)校驗(yàn)使用JSR380默認(rèn)注解（@NotBlank、@Size等），配合@Valid觸發(fā)校驗(yàn)；2. 全局異常捕獲校驗(yàn)失敗異常，統(tǒng)一返回響應(yīng)格式；3. 特殊場景使用自定義校驗(yàn)注解，實(shí)現(xiàn)校驗(yàn)邏輯復(fù)用；4. 復(fù)雜場景可通過分組校驗(yàn)，實(shí)現(xiàn)差異化校驗(yàn)需求。

通過這種方式，不僅提升了代碼的可讀性和可維護(hù)性，還降低了后期的維護(hù)成本，同時(shí)讓接口返回的提示信息更友好，符合企業(yè)級(jí)開發(fā)的規(guī)范，是Spring Boot接口開發(fā)中參數(shù)校驗(yàn)的最優(yōu)實(shí)踐之一。

到此這篇關(guān)于Spring Boot 參數(shù)校驗(yàn)全局處理(JSR380 + 自定義校驗(yàn))的文章就介紹到這了,更多相關(guān)Spring Boot 參數(shù)校驗(yàn)全局內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論