SpringBoot接口参数校验从入门到精通的完整指南

@postmapping("/register")
public string register(user user) {
    // 手动校验每个字段
    if (user.getusername() == null || user.getusername().isempty()) {
        return "用户名不能为空";
    }
    if (user.getpassword() == null || user.getpassword().length() < 6) {
        return "密码长度不能小于6位";
    }
    if (user.getemail() == null || !user.getemail().contains("@")) {
        return "邮箱格式不正确";
    }
    if (user.getage() == null || user.getage() < 0 || user.getage() > 150) {
        return "年龄不合法";
    }
    // ... 继续业务逻辑
}

<dependency>
    <groupid>org.springframework.boot</groupid>
    <artifactid>spring-boot-starter-validation</artifactid>
</dependency>

import javax.validation.constraints.*;
public class userregisterdto {
@notblank(message = "用户名不能为空")
private string username;

@notblank(message = "密码不能为空")
@size(min = 6, max = 20, message = "密码长度必须在6-20位之间")
private string password;

@notblank(message = "邮箱不能为空")
@email(message = "邮箱格式不正确")
private string email;

@notnull(message = "年龄不能为空")
@min(value = 1, message = "年龄最小为1岁")
@max(value = 150, message = "年龄最大为150岁")
private integer age;

// getter / setter 省略
}

@restcontroller
@requestmapping("/api/user")
public class usercontroller {
@postmapping("/register")
public result register(@valid @requestbody userregisterdto dto) {
    // 如果校验不通过，根本不会执行到这里
    // 这里只管写业务逻辑
    userservice.register(dto);
    return result.success("注册成功");
}
}

@min(value = 1, message = "数量至少为1")
@max(value = 999, message = "数量不能超过999")
private integer quantity;
@decimalmin(value = "0.01", message = "金额至少为0.01")
@decimalmax(value = "999999.99", message = "金额不能超过999999.99")
private bigdecimal amount;

@past(message = "生日必须是过去的时间")
private localdate birthday;
@future(message = "有效期必须晚于当前时间")
private localdatetime expiretime;
@asserttrue(message = "必须同意用户协议")
private boolean agreeprotocol;

public interface creategroup {}   // 新增分组
public interface updategroup {}   // 更新分组

public class userdto {
@notnull(message = "id不能为空", groups = updategroup.class)
private long id;

@notblank(message = "用户名不能为空", groups = {creategroup.class, updategroup.class})
private string username;

@notblank(message = "密码不能为空", groups = creategroup.class)  // 新增时必填
@size(min = 6, max = 20, message = "密码长度6-20位")
private string password;

@email(message = "邮箱格式不正确")
private string email;  // 没指定分组，默认在所有分组都生效
}

@restcontroller
@requestmapping("/api/user")
public class usercontroller {
@postmapping("/create")   // 新增时使用 creategroup
public result create(@validated(creategroup.class) @requestbody userdto dto) {
    // 此时会校验：id（不校验，因为没有在creategroup中标记）、username（校验）、password（校验）
    userservice.create(dto);
    return result.success();
}

@putmapping("/update")    // 更新时使用 updategroup
public result update(@validated(updategroup.class) @requestbody userdto dto) {
    // 此时会校验：id（校验）、username（校验）、password（不校验，因为没有在updategroup中标记）
    userservice.update(dto);
    return result.success();
}
}

import javax.validation.constraint;
import javax.validation.payload;
import java.lang.annotation.*;
@documented
@constraint(validatedby = gendervalidator.class)  // 指定校验器
@target({elementtype.field})
@retention(retentionpolicy.runtime)
public @interface gender {
string message() default "性别只能是 male 或 female";

class<?>[] groups() default {};

class<? extends payload>[] payload() default {};
}

import javax.validation.constraintvalidator;
import javax.validation.constraintvalidatorcontext;
public class gendervalidator implements constraintvalidator<gender, string> {
@override
public boolean isvalid(string value, constraintvalidatorcontext context) {
    if (value == null) {
        return true;  // 允许为空，由 @notnull 控制是否必填
    }
    return "male".equals(value) || "female".equals(value);
}
}

public class userdto {
    @gender(message = "性别只能填 male 或 female")
    private string gender;
}

import org.springframework.http.httpstatus;
import org.springframework.validation.fielderror;
import org.springframework.web.bind.methodargumentnotvalidexception;
import org.springframework.web.bind.annotation.exceptionhandler;
import org.springframework.web.bind.annotation.responsestatus;
import org.springframework.web.bind.annotation.restcontrolleradvice;
import java.util.hashmap;
import java.util.map;
@restcontrolleradvice
public class globalexceptionhandler {
/**
 * 处理 @valid 校验失败异常
 */
@exceptionhandler(methodargumentnotvalidexception.class)
@responsestatus(httpstatus.bad_request)
public result handlevalidationexception(methodargumentnotvalidexception e) {
    // 收集所有字段的校验失败信息
    map<string, string> errors = new hashmap<>();
    e.getbindingresult().getallerrors().foreach(error -> {
        string fieldname = ((fielderror) error).getfield();
        string errormessage = error.getdefaultmessage();
        errors.put(fieldname, errormessage);
    });
    return result.error(400, "参数校验失败", errors);
}
}

{
    "code": 400,
    "message": "参数校验失败",
    "data": {
        "username": "用户名不能为空",
        "password": "密码长度必须在6-20位之间"
    }
}

@postmapping("/batch")
public result batch(@valid @requestbody list<userdto> userlist) {  // list 不支持 @valid
    // ...
}

@data
public class userlistdto {
    @valid
    private list<userdto> userlist;
}
@postmapping("/batch")
public result batch(@valid @requestbody userlistdto dto) {
// ...
}

public class orderdto {
    @notnull
    private long userid;
    // 没有加 @valid，address 内部的校验不生效
    private addressdto address;
}

public class orderdto {
    @notnull
    private long userid;
@valid  // 必须加 @valid 才能触发嵌套校验
private addressdto address;
}

logger.error("校验失败，参数：{}", dto);  // 可能包含密码

logger.error("校验失败，用户：{}，字段：{}", dto.getusername(), errors);