<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
    <!-- 無需指定版本，Spring Boot 父工程已統(tǒng)一管理 -->
</dependency>

import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.validation.Valid;
import javax.servlet.http.HttpServletRequest;

@RestController
@RequestMapping("/test")
// 類上添加 @Validated 可支持方法參數(shù)（非對(duì)象）的校驗(yàn)
@Validated
public class TestController {

    /**
     * 測(cè)試對(duì)象參數(shù)校驗(yàn)
     * @param req 待校驗(yàn)的請(qǐng)求對(duì)象
     * @param request 請(qǐng)求上下文
     * @return 響應(yīng)結(jié)果
     */
    @RequestMapping(value = "/req.json")
    public Object test(@Valid TestRequest req, HttpServletRequest request) {
        // 校驗(yàn)通過后才會(huì)執(zhí)行此處業(yè)務(wù)邏輯
        return "請(qǐng)求成功，req=" + req.getReq();
    }

    /**
     * 擴(kuò)展：基本類型參數(shù)校驗(yàn)（需類上添加 @Validated）
     * 校驗(yàn)不通過會(huì)拋出 ConstraintViolationException
     */
    @RequestMapping(value = "/base.json")
    public Object testBaseParam(
            @NotBlank(message = "用戶名不能為空") String username,
            @Min(value = 18, message = "年齡不能小于18歲") Integer age) {
        return "用戶名：" + username + "，年齡：" + age;
    }
}

import javax.validation.constraints.NotBlank;

public class TestRequest {

    // @NotBlank：字符串不能為 null 且去除首尾空格后長度 > 0
    @NotBlank(message = "req參數(shù)不能為空（不能是空白字符）")
    private String req;

    // 必須提供 getter/setter，否則 Spring MVC 無法注入?yún)?shù)
    public String getReq() {
        return req;
    }

    public void setReq(String req) {
        this.req = req;
    }
}

import org.springframework.context.MessageSource;
import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.validation.ObjectError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import javax.annotation.Resource;
import javax.validation.ConstraintViolation;
import javax.validation.ConstraintViolationException;
import java.util.Locale;
import java.util.Set;

/**
 * 全局異常處理器：統(tǒng)一處理參數(shù)校驗(yàn)異常
 */
@RestControllerAdvice
public class GlobalValidationExceptionHandler {

    // 用于國際化消息解析（可選）
    @Resource
    private MessageSource messageSource;

    /**
     * 處理對(duì)象參數(shù)校驗(yàn)異常（@Valid 標(biāo)記的對(duì)象）
     * 包括：BindException（表單提交）、MethodArgumentNotValidException（JSON 提交）
     */
    @ExceptionHandler({BindException.class, MethodArgumentNotValidException.class})
    public Result<?> handleObjectValidationException(Exception ex) {
        ObjectError objectError = null;
        // 區(qū)分不同的對(duì)象校驗(yàn)異常類型
        if (ex instanceof BindException) {
            // 表單提交（application/x-www-form-urlencoded）
            objectError = ((BindException) ex).getBindingResult().getAllErrors().get(0);
        } else if (ex instanceof MethodArgumentNotValidException) {
            // JSON 提交（application/json）
            objectError = ((MethodArgumentNotValidException) ex).getBindingResult().getAllErrors().get(0);
        }

        // 解析錯(cuò)誤信息（支持國際化）
        Locale locale = LocaleContextHolder.getLocale();
        String errorMsg = messageSource.getMessage(objectError, locale);
        return Result.error(400, "參數(shù)校驗(yàn)失敗", errorMsg);
    }

    /**
     * 處理基本類型/單個(gè)參數(shù)校驗(yàn)異常（@Validated 標(biāo)記的類）
     */
    @ExceptionHandler(ConstraintViolationException.class)
    public Result<?> handleBaseParamValidationException(ConstraintViolationException ex) {
        Set<ConstraintViolation<?>> violations = ex.getConstraintViolations();
        // 獲取第一個(gè)錯(cuò)誤信息（也可收集所有錯(cuò)誤）
        String errorMsg = violations.iterator().next().getMessage();
        return Result.error(400, "參數(shù)校驗(yàn)失敗", errorMsg);
    }

    // 通用響應(yīng)類（簡化示例）
    static class Result<T> {
        private int code;
        private String msg;
        private T data;

        public static <T> Result<T> error(int code, String msg, T data) {
            Result<T> result = new Result<>();
            result.code = code;
            result.msg = msg;
            result.data = data;
            return result;
        }

        public static <T> Result<T> success(T data) {
            Result<T> result = new Result<>();
            result.code = 200;
            result.msg = "操作成功";
            result.data = data;
            return result;
        }

        // getter/setter 省略
    }
}

import javax.validation.constraints.*;
import java.time.LocalDateTime;

public class UserRequest {
    @NotBlank(message = "用戶名不能為空")
    @Size(min = 2, max = 20, message = "用戶名長度必須在2-20個(gè)字符之間")
    private String username;

    @NotNull(message = "年齡不能為空")
    @Min(value = 18, message = "年齡不能小于18歲")
    @Max(value = 60, message = "年齡不能大于60歲")
    private Integer age;

    @Email(message = "郵箱格式不正確", regexp = "^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$")
    private String email;

    @Past(message = "生日必須是過去的時(shí)間")
    private LocalDateTime birthday;

    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手機(jī)號(hào)格式不正確")
    private String phone;

    @DecimalMin(value = "0.01", message = "金額不能小于0.01")
    @DecimalMax(value = "10000.00", message = "金額不能大于10000.00")
    private Double amount;

    // getter/setter 省略
}

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.*;

/**
 * 自定義手機(jī)號(hào)校驗(yàn)注解
 */
@Target({ElementType.FIELD, ElementType.PARAMETER}) // 支持字段和方法參數(shù)
@Retention(RetentionPolicy.RUNTIME) // 運(yùn)行時(shí)生效
@Documented
@Constraint(validatedBy = PhoneValidator.class) // 關(guān)聯(lián)自定義驗(yàn)證器
public @interface Phone {

    // 錯(cuò)誤提示信息（支持國際化，默認(rèn)值可引用配置文件）
    String message() default "手機(jī)號(hào)格式不正確（必須是11位有效手機(jī)號(hào)）";

    // 校驗(yàn)分組（用于多場(chǎng)景校驗(yàn)，如新增/編輯不同規(guī)則）
    Class<?>[] groups() default {};

    // 負(fù)載信息（用于傳遞額外校驗(yàn)元數(shù)據(jù)）
    Class<? extends Payload>[] payload() default {};
}

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import java.util.regex.Pattern;

/**
 * 手機(jī)號(hào)校驗(yàn)器：實(shí)現(xiàn) ConstraintValidator 接口
 */
public class PhoneValidator implements ConstraintValidator<Phone, String> {

    // 手機(jī)號(hào)正則表達(dá)式（支持13-9開頭的11位數(shù)字）
    private static final Pattern PHONE_PATTERN = Pattern.compile("^1[3-9]\\d{9}$");

    /**
     * 初始化方法：可獲取注解的屬性值（如自定義正則）
     */
    @Override
    public void initialize(Phone constraintAnnotation) {
        // 若注解有自定義屬性（如 regexp），可在此處獲取并初始化
        ConstraintValidator.super.initialize(constraintAnnotation);
    }

    /**
     * 校驗(yàn)核心方法：返回 true 表示校驗(yàn)通過，false 表示失敗
     * @param value 待校驗(yàn)的值（手機(jī)號(hào)字符串）
     * @param context 校驗(yàn)上下文（可用于自定義錯(cuò)誤信息）
     */
    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        // 1. 允許值為 null（若不允許 null，需配合 @NotNull 注解）
        if (value == null) {
            return true;
        }
        // 2. 正則匹配校驗(yàn)
        return PHONE_PATTERN.matcher(value).matches();
    }
}

public class UserRequest {
    @Phone(message = "手機(jī)號(hào)格式錯(cuò)誤，請(qǐng)輸入11位有效手機(jī)號(hào)")
    private String phone;

    // 配合 @NotNull 注解，禁止手機(jī)號(hào)為 null
    @NotNull(message = "手機(jī)號(hào)不能為空")
    @Phone
    private String requiredPhone;

    // getter/setter 省略
}

// 1. 定義分組接口（無需實(shí)現(xiàn)）
public interface AddGroup {}
public interface UpdateGroup {}

// 2. 注解指定分組
public class UserRequest {
    @NotNull(groups = AddGroup.class, message = "新增時(shí)ID不能為空")
    @Null(groups = UpdateGroup.class, message = "編輯時(shí)ID必須為空")
    private Long id;

    @NotBlank(groups = {AddGroup.class, UpdateGroup.class}, message = "用戶名不能為空")
    private String username;
}

// 3. Controller 指定分組校驗(yàn)
@RestController
@RequestMapping("/user")
public class UserController {
    // 新增用戶：只校驗(yàn) AddGroup 分組的注解
    @PostMapping("/add")
    public Result<?> add(@Validated(AddGroup.class) UserRequest request) {
        return Result.success("新增成功");
    }

    // 編輯用戶：只校驗(yàn) UpdateGroup 分組的注解
    @PostMapping("/update")
    public Result<?> update(@Validated(UpdateGroup.class) UserRequest request) {
        return Result.success("編輯成功");
    }
}

public class UserRequest {
    @NotBlank(message = "用戶名不能為空")
    private String username;

    // 嵌套對(duì)象校驗(yàn)：必須添加 @Valid 注解
    @Valid
    @NotNull(message = "地址信息不能為空")
    private AddressRequest address;

    // 嵌套對(duì)象類
    public static class AddressRequest {
        @NotBlank(message = "省份不能為空")
        private String province;

        @NotBlank(message = "城市不能為空")
        private String city;

        // getter/setter 省略
    }

    // getter/setter 省略
}

# src/main/resources/messages.properties（默認(rèn)）
user.username.notBlank=用戶名不能為空
user.phone.invalid=手機(jī)號(hào)格式不正確

# src/main/resources/messages_zh_CN.properties（中文）
user.username.notBlank=用戶名不能為空
user.phone.invalid=手機(jī)號(hào)格式不正確

# src/main/resources/messages_en_US.properties（英文）
user.username.notBlank=Username cannot be blank
user.phone.invalid=Phone number format is invalid

public class UserRequest {
    @NotBlank(message = "{user.username.notBlank}")
    private String username;

    @Phone(message = "{user.phone.invalid}")
    private String phone;
}