Spring Boot JSR 380 参数校验实战：@NotNull、@Email、@Size 完整指南

在开发 Web 应用时，参数校验是保障接口安全和质量的最重要环节之一。Spring Boot 提供了简洁而强大的方法，让我们能够利用 Java 校验 API (JSR 380) 中定义的注解进行参数校验。

前言

JSR 380（Bean Validation 2.0）是 Java Bean 验证规范，它定义了一系列注解，用于验证 Java Bean 对象的属性是否满足特定条件。

在后端业务开发中，JSR 380 参数校验已成为标配。它能帮助我们：

• 提前拦截无效请求，减少后端数据库写入
• 提升接口性能和用户体验
• 实现“零容错”的健壮性

本小节将带大家深入学习 JSR 380 的核心注解，并结合 Spring Boot 实战，教你如何优雅地使用它。

JSR 380 是什么？

JSR 380 是 Bean Validation 2.0 的官方名称，属于 Java EE 规范，由 Oracle 领导制定。

它包括：

• 一系列验证注解（@NotNull、@Email、@Size 等）
• 验证器接口（Validator）
• 异常处理机制

Spring Boot 2.0+ 版本默认已内置了对 JSR 380 的支持，无需额外引入依赖。

JSR 380 核心注解详解

1. 必填校验类

2. 数值校验类

3. 格式校验类

4. 日期校验类

5. 布尔值校验类

Spring Boot 集成 JSR 380 实战

1. 编写校验实体类

import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;

public class UserRegisterDTO {

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在 3-20 之间")
    private String username;

    @NotNull(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;

    @NotNull(message = "密码不能为空")
    @Size(min = 6, message = "密码长度至少为 6 位")
    private String password;

    // Getter + Setter
}

2. 使用 @Valid 进行验证

import jakarta.validation.Valid;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @PostMapping("/register")
    public String register(@Valid @RequestBody UserRegisterDTO dto, BindingResult result) {
        if (result.hasErrors()) {
            return result.getFieldError().getDefaultMessage();
        }
        return "注册成功！";
    }
}

3. 全局异常处理

import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public String handleMethodArgumentNotValidException(MethodArgumentNotValidException ex) {
        return ex.getMessage();
    }
}

JSR 380 vs Jakarta Bean Validation 对比

推荐使用 Jakarta Bean Validation，因为它是未来的规范方向，Spring Boot 3.0+ 已全面切换到 Jakarta 命名空间。

自定义校验注解（JSR 380 扩展）

除了标准注解外，我们还可以定义自己的校验注解：

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

@Documented
@Constraint(validatedBy = MySpecialValidator.class)
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface MySpecial {
    String message() default "自定义校验失败";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

总结

JSR 380（Bean Validation）是 Spring Boot 开发中最常用的参数校验方案之一。通过标准注解 + AOP 切面 + 全局异常处理，我们可以轻松实现“声明式校验”。

掌握 JSR 380 后，你的接口将更加健壮、安全、高效。

相关内链推荐：

• Spring Boot AOP 实现 API 请求日志切面（自定义注解实战）
• Spring Boot 高并发使用 MDC 实现唯一请求日志追踪（彻底解决日志交错）
• Logback 日志框架详解：Spring Boot 必备的日志管理工具

SEO 优化建议：

• 标题包含核心关键词：“JSR 380”、“参数校验”、“@NotNull”、“Spring Boot”。
• 建议添加更多代码截图，提升用户动手能力。