java

关注公众号 jb51net

关闭
首页 > 软件编程 > java > SpringBoot参数校验全指南

SpringBoot参数校验全指南分享

作者：Vintanz

这篇文章主要介绍了SpringBoot参数校验全指南,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教

在 Web 开发中，参数校验是保障接口安全性和数据合法性的关键环节。

手动编写校验逻辑不仅繁琐，还容易遗漏边界情况。

Spring Boot 整合了 validation 工具，提供了一套简洁高效的参数校验方案，可快速实现对简单数据类型、对象类型的校验，并支持自定义异常处理。

一、参数校验入门：简单数据类型校验

1. 引入依赖

Spring Boot 提供了 spring-boot-starter-validation 起步依赖，内置了参数校验所需的核心组件：

<!-- 参数校验依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

2. 开启参数校验

在控制器类上添加 @Validated 注解，开启参数校验功能：

@Validated // 开启参数校验
@Controller
public class TestController {
    // 接口方法...
}

3. 常用校验注解

对简单数据类型（如字符串、数字）的校验，可直接在方法参数上添加校验注解。

常用注解如下：

注解作用示例
@NotBlank字符串不为 null 且去除空格后不为空串@NotBlank String username
@NotNull对象不为 null（适用于包装类）@NotNull Integer age
@NotEmpty集合不为 null 且不为空@NotEmpty List<String> ids
@Min数字最小值@Min(0) Integer score
@Max数字最大值@Max(150) Integer age
@Email字符串符合邮箱格式@Email String email
@Length字符串长度在指定范围内@Length(min=2, max=10) String name

4. 简单类型校验示例

@Validated
@Controller
public class TestController {
    @RequestMapping("/user")
    @ResponseBody
    public String addUser(
        @NotBlank(message = "用户名不能为空") String username, // 非空校验
        @NotNull(message = "年龄不能为空") @Min(0) @Max(150) Integer age, // 非空+范围校验
        @Email(message = "邮箱格式不正确") String email // 格式校验
    ) {
        return "参数校验通过：" + username + ", " + age + ", " + email;
    }
}

二、异常处理：统一响应错误信息

参数校验失败后，Spring Boot 会默认抛出异常并返回 400 错误，但默认的错误信息不够友好。我们可以通过以下两种方式统一处理校验异常：

1. 自定义错误页面（适用于前后端不分离）

Spring Boot 会自动跳转至 src/main/resources/templates/error.html 页面，可在该页面展示友好的错误提示：

<!-- error.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>错误提示</title>
</head>
<body>
    <h1>参数错误</h1>
    <p>请检查输入的参数是否符合要求</p>
</body>
</html>

2. 全局异常处理器（适用于前后端分离）

通过 @ControllerAdvice 定义全局异常处理器，捕获校验异常并返回 JSON 格式的错误信息：

@ControllerAdvice
@ResponseBody
public class GlobalExceptionHandler {
    // 处理简单类型参数校验异常
    @ExceptionHandler(ConstraintViolationException.class)
    public Map<String, String> handleConstraintViolationException(ConstraintViolationException e) {
        Map<String, String> errorMap = new HashMap<>();
        // 获取所有校验失败的信息
        e.getConstraintViolations().forEach(violation -> {
            String field = violation.getPropertyPath().toString(); // 参数名
            String message = violation.getMessage(); // 错误信息
            errorMap.put(field, message);
        });
        return errorMap;
    }
}

当参数校验失败时，会返回类似以下的 JSON 响应：

{
  "username": "用户名不能为空",
  "email": "邮箱格式不正确"
}

三、对象类型参数校验

对于复杂业务场景，接口通常接收对象类型的参数（如用户注册信息、订单信息）。

此时需对对象的每个属性进行校验，步骤如下：

1. 定义实体类并添加校验注解

在实体类的字段上添加校验注解，指定校验规则和错误提示：

public class User {
    @NotNull(message = "ID不能为空")
    private Integer id;

    @NotBlank(message = "姓名不能为空")
    @Length(min = 2, max = 10, message = "姓名长度必须在2-10之间")
    private String name;

    @NotNull(message = "年龄不能为空")
    @Min(value = 0, message = "年龄不能为负数")
    @Max(value = 150, message = "年龄不能超过150")
    private Integer age;

    // getter + setter（必须存在，否则校验不生效）
}

2. 在控制器中校验对象

在控制器方法的对象参数前添加 @Validated 注解，并通过 BindingResult 捕获校验结果：

@Controller
public class UserController {
    @RequestMapping("/addUser")
    @ResponseBody
    public String addUser(
        @Validated User user, // 开启对象校验
        BindingResult result // 用于接收校验结果
    ) {
        // 判断是否有校验失败
        if (result.hasErrors()) {
            // 收集所有错误信息
            StringBuilder errorMsg = new StringBuilder();
            result.getAllErrors().forEach(error -> {
                FieldError fieldError = (FieldError) error;
                errorMsg.append(fieldError.getField()).append(":").append(fieldError.getDefaultMessage()).append("; ");
            });
            return "参数错误：" + errorMsg.toString();
        }
        // 校验通过，处理业务逻辑
        return "用户添加成功：" + user.getName();
    }
}

四、常见问题与最佳实践

1. 校验注解不生效？

2. 如何自定义校验规则？

除了内置注解，还可通过 @Pattern 注解自定义正则校验，例如校验手机号：

@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
private String phone;

3. 全局异常处理器的优势

使用 @ControllerAdvice 定义全局异常处理器，可统一处理所有校验异常，避免在每个接口中重复编写错误处理逻辑，提高代码复用性。

总结

Spring Boot 的参数校验机制通过注解化的方式，极大简化了数据合法性校验的实现。

本文介绍了简单类型、对象类型的校验方法，以及异常处理方案，涵盖了从基础到实战的核心场景。合理使用参数校验，不仅能减少手动校验代码，还能提高接口的健壮性和安全性。

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。

您可能感兴趣的文章:
阅读全文