Spring Boot 数据校验

在企业开发中，参数校验是保证数据合法性的重要环节。Spring Boot 通过 Bean Validation 提供了简单而强大的校验机制。本文将从依赖引入、常见校验注解、数据校验的开启、以及错误处理等方面，详细介绍如何在 Spring Boot 项目中使用数据校验功能。

---

一、引入数据校验依赖

在 Spring Boot 项目中，数据校验功能可以通过 Bean Validation API 实现。Spring Boot 2.5.15 版本默认集成了 javax.validation，但为了确保功能完整性，可以手动引入以下依赖。

步骤：

1. 打开项目的 pom.xml 文件。
2. 添加如下依赖，确保引入 Spring Boot 的校验模块。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

二、常见的校验注解

Spring Boot 基于 javax.validation 提供了一系列常用的校验注解，可以对参数的合法性进行检查。以下列举了一些常用注解，并详细说明其用途。

注解	描述	用法示例
@NotNull	检查字段是否为 null	@NotNull private String name;
@NotBlank	检查字段是否为空字符串（不能为 null 且不能为空字符串）	@NotBlank private String username;
@NotEmpty	检查集合类字段是否为空	@NotEmpty private List<String> items;
@Size	检查集合或字符串的长度	@Size(min = 2, max = 10) private String description;
@Max	检查字段的最大值	@Max(100) private Integer age;
@Min	检查字段的最小值	@Min(18) private Integer age;
@Email	检查字段是否是合法的电子邮件地址	@Email private String email;
@Pattern	检查字段是否符合给定的正则表达式	@Pattern(regexp = "^\\d{10}$") private String phone;

三、在实体类中使用校验注解

例如 Favorite 实体类，用户可以通过此类创建或更新收藏夹信息。我们将在该实体类上使用校验注解，确保字段数据的合法性。

package com.example.entity;

import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * 表示用户收藏夹的实体类
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Favorite {

    /**
     * 收藏夹的标题，不能为空，且长度为2-20个字符
     */
    @NotBlank(message = "收藏夹标题不能为空")
    @Size(min = 2, max = 20, message = "收藏夹标题长度应在2-20个字符之间")
    private String title;

    /**
     * 收藏夹的简介，最大长度为200个字符
     */
    @Size(max = 200, message = "简介不能超过200个字符")
    private String description;

    /**
     * 收藏夹是否公开，0为私密，1为公开
     */
    @NotNull(message = "公开状态不能为空")
    private Integer visible;
    
    /**
     * 收藏夹封面的URL，可选字段
     */
    private String cover;   // 收藏夹封面url，可为空
}

四、开启校验功能

要在 Spring Boot 项目中启用数据校验，必须在 Controller 层的方法参数上使用 @Valid 或 @Validated 注解。

1. 使用 @Valid 注解

@Valid 是 Bean Validation 标准的一部分，可以在简单场景下使用，用于触发对象及其嵌套对象的校验。

示例：

import org.springframework.web.bind.annotation.*;
import javax.validation.Valid;

@RestController
@RequestMapping("/api/favorite")
public class FavoriteController {

    /**
     * 创建新的收藏夹
     * @param favorite 收藏夹对象，需进行数据校验
     * @return 创建结果
     */
    @PostMapping("/create")
    public ResponseEntity<?> createFavorite(@Valid @RequestBody Favorite favorite) {
        // 校验通过后执行的逻辑
        return ResponseEntity.ok("收藏夹创建成功");
    }
}

2. 使用 @Validated 注解

@Validated 是 Spring 提供的注解，除了能够实现 @Valid 的功能，还可以支持 分组校验。

示例：

import org.springframework.validation.annotation.Validated;

@RestController
@RequestMapping("/api/favorite")
@Validated  // 可以加在类上，也可以加在方法上
public class FavoriteController {

    @PostMapping("/create")
    public ResponseEntity<?> createFavorite(@Validated @RequestBody Favorite favorite) {
        return ResponseEntity.ok("收藏夹创建成功");
    }
}

五、处理校验错误

当校验失败时，Spring 会抛出 MethodArgumentNotValidException 或 ConstraintViolationException。通过全局异常处理机制可以捕获这些异常，并返回用户友好的错误信息。

全局异常处理器示例：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.util.HashMap;
import java.util.Map;

/**
 * 全局异常处理器，用于捕获校验失败的异常
 */
@RestControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 处理校验失败抛出的异常
     * @param ex MethodArgumentNotValidException 异常对象
     * @return 包含错误信息的响应体
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        for (FieldError error : ex.getBindingResult().getFieldErrors()) {
            errors.put(error.getField(), error.getDefaultMessage());
        }
        return new ResponseEntity<>(errors, HttpStatus.BAD_REQUEST);
    }
}

六、结合分组校验

在某些情况下，不同的操作（如创建和更新）可能需要不同的校验规则。此时可以通过分组校验实现更灵活的校验逻辑。

1. 定义分组接口：

public interface CreateGroup {}
public interface UpdateGroup {}

2. 在实体类中使用分组校验：

public class Favorite {

    @NotBlank(message = "收藏夹标题不能为空", groups = CreateGroup.class)
    @Size(min = 2, max = 20, message = "收藏夹标题长度应在2-20个字符之间", groups = {CreateGroup.class, UpdateGroup.class})
    private String title;

    @Size(max = 200, message = "简介不能超过200个字符", groups = {CreateGroup.class, UpdateGroup.class})
    private String description;

    @NotNull(message = "公开状态不能为空", groups = CreateGroup.class)
    private Integer visible;
}

3. 在 Controller 中指定分组：

@PostMapping("/create")
public ResponseEntity<?> createFavorite(@Validated(CreateGroup.class) @RequestBody Favorite favorite) {
    return ResponseEntity.ok("收藏夹创建成功");
}

@PutMapping("/update")
public ResponseEntity<?> updateFavorite(@Validated(UpdateGroup.class) @RequestBody Favorite favorite) {
    return ResponseEntity.ok("收藏夹更新成功");
}

---

七、总结

1. 依赖引入：确保 spring-boot-starter-validation 依赖已引入。
2. 常用注解：了解并掌握常见校验注解的使用方法。
3. 启用校验：通过 @Valid 或 @Validated 注解启用参数校验。
4. 处理错误：使用全局异常处理器，捕获并处理校验失败的错误。
5. 分组校验：使用 @Validated 注解和分组接口，针对不同操作场景执行不同的校验规则。

通过本文的讲解，开发者可以在项目中轻松集成并使用 Spring Boot 的数据校验功能，确保数据的合法性和稳定性。