Bean Validation 註解詳解：@NotNull vs @NotEmpty vs @NotBlank 差異與適用場景

快速對照表

源碼級深度解析

@NotNull — 最基礎的非空校驗

/**
 * The annotated element must not be {@code null}.
 * Accepts any type.
 */
@Target({FIELD, METHOD, PARAMETER, ANNOTATION_TYPE})
@Retention(RUNTIME)
public @interface NotNull { }

• 僅檢查引用是否為 null
• 基本類型（int、boolean 等）永不為 null，無需標註
• 包裝類型、引用類型均適用

@NotEmpty — 集合與字符串長度校驗

/**
 * Asserts that the annotated string, collection, map or array 
 * is not {@code null} or empty.
 */
@Target({FIELD, METHOD, PARAMETER, ANNOTATION_TYPE})
@Retention(RUNTIME)
public @interface NotEmpty { }

• String：length() > 0
• Collection/Map：size() > 0
• Array：length > 0
• 不檢查空白字符：" " 視為非空

@NotBlank — 字符串實質內容校驗

/**
 * Validate that the annotated string is not {@code null} or empty.
 * The difference to {@code NotEmpty} is that trailing whitespaces 
 * are getting ignored.
 */
@Target({FIELD, METHOD, PARAMETER, ANNOTATION_TYPE})
@Retention(RUNTIME)
public @interface NotBlank { }

• 僅適用於 String
• 內部調用 CharSequence.trim().length() > 0
• 過濾：空字符串、null、純空格、製表符、換行符
• 業務場景：用戶名、密碼、搜索關鍵詞等「必須有實質輸入」字段

實戰選型指南

場景 1：數據庫非空字段

@NotNull
private Long userId;        // 外鍵 ID，不可為 null

@NotBlank
private String username;    // 業務主鍵，不可為空白

@NotEmpty
private List<String> tags;  // 標籤集合，至少一個

場景 2：表單提交驗證

@NotBlank(message = "手機號不能為空")
private String phone;

@NotBlank(message = "驗證碼不能為空")
private String captcha;

@NotEmpty(message = "至少選擇一個興趣標籤")
private List<String> interests;

場景 3：DTO 字段組合驗證

public class AddressDTO {
    @NotBlank(message = "省份必填")
    private String province;
    
    @NotBlank(message = "城市必填")
    private String city;
    
    @NotEmpty(message = "詳細地址不能為空")
    private String detail; // 允許空格但不可全空
}

常見誤區與避坑

1. 基本類型加 @NotNull：int 默認 0，永不為 null，註解無效
2. @NotEmpty 用於 String 卻期望過濾空格：需改用 @NotBlank
3. @NotBlank 用於集合：編譯報錯，僅支援 CharSequence
4. 組合使用語義重複：@NotBlank 隱含 @NotEmpty 隱含 @NotNull，單用最強者即可

擴展：自定義註解組合

@Target({FIELD, METHOD, PARAMETER})
@Retention(RUNTIME)
@NotNull
@NotBlank
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手機號格式錯誤")
public @interface ValidPhone {
    String message() default "手機號格式錯誤";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

總結

記住核心口訣：基本類型不用標，引用類型防 null 用 @NotNull；集合字符串防空用 @NotEmpty；字符串防空白必用 @NotBlank。正確選型能減少無效校驗代碼，提升 API 健壯性與可讀性。