03 后端入参校验：自定义注解实现

一、前言

在 Java 后端开发中，为了实现入参校验，常常会使用一些特定的注解来标记参数的约束条件。这些注解通常与一个校验框架（如 Spring Boot 提供的 @Valid 等）配合使用，以便在方法调用前自动进行参数校验。以下是一些常见的用于入参校验的注解：

• @NotNull： 适用于任何对象，包括基本类型、包装类型、集合类、Map等，判断对象本身是否为null，但是无法校验空字符串。

• @NotEmpty： 适用于集合类（如 List 、Set）、数组、Map、CharSequence（如 String ）等，判断是否非空（即长度不为0）。

• @NotBlank： 专门用于 CharSequence（如 String ）。不仅可以校验null，同时还可以校验空字符串。

如果以上注解实际情况都不能用，需要自定义注解取代它们。

二、实现

1、新建Spring Boot项目

此步骤略过~

2、引入依赖

可以根据 GAV坐标 ，去 Maven官网 查询依赖版本。
Maven Repository: Search/Browse/Explore

<!-- Hibernate Validator: 强大的数据验证框架 -->
<dependency>  
    <groupId>org.hibernate.validator</groupId>  
    <artifactId>hibernate-validator</artifactId>  
    <version>版本号</version>  
</dependency>

<!-- Spring Messaging: 处理消息传递相关的注解。如：@Payload -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-messaging</artifactId>
    <version>当前Spring框架版本号</version>
</dependency>
1
2
3
4
5
6
7
8
9
10
11
12
13

3、新建注解类

package com.demo.springboot3.ParamValid;

import jakarta.validation.Constraint;
import org.springframework.messaging.handler.annotation.Payload;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * @Description: // 参数校验：注解
 * @Author: M.
 * @Date: 2024-04-25 18:35
 */
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = ParamValidator.class)
public @interface ParamValid {
    // message支持自定义
    String message() default  "该字段不能为空！";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

• @Target
  定义： 指定一个注解能够合法应用的位置。

• @Retention：
  定义： 指定一个自定义注解在何时何地保持其存在性。

• @Constraint：
  定义： 在Bean Validation框架中@Constraint 是一个元注解，用于标记一个类为自定义验证约束注解。

4、新建校验器

package com.demo.springboot3.ParamValid;

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

import java.util.Collection;
import java.util.Map;

/**
 * @Description: // 参数校验：校验器
 * @Author: M.
 * @Date: 2024-04-25 19:17
 */
public class ParamValidator implements ConstraintValidator<ParamValid, Object> {
    @Override
    public void initialize(ParamValid constraintAnnotation) {
        ConstraintValidator.super.initialize(constraintAnnotation);
    }

    @Override
    public boolean isValid(Object value, ConstraintValidatorContext constraintValidatorContext) {
        return value != null // 参数不为null
                && !((value instanceof CharSequence && ((CharSequence) value).length() == 0) // 字符串不为空，同时校验了空字符串
                || (value instanceof Collection && ((Collection<?>) value).isEmpty()) // 集合不为空
                || (value instanceof Map && ((Map<?,?>) value).isEmpty())); // Map不为空
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

• ParamValid： 上文定义的注解名称
• Object： 校验器的入参，需要检验的参数。

5、全局异常处理器

package com.demo.springboot3.ParamValid;

import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;

import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

/**
 * @Description: // 参数校验：全局异常处理器
 * @Author: M.
 * @Date: 2024-04-25 19:35
 */
@ControllerAdvice
public class PVGlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ResponseEntity<Map<String, Object>> handleValidationExceptions(MethodArgumentNotValidException ex, HttpServletRequest request){
        Map<String, Object> body = new HashMap<>();
        body.put("timestamp", new Date());
        body.put("status", HttpStatus.BAD_REQUEST.value());
        body.put("path",request.getRequestURI());

        List<Map<String, String>> errorMessages = ex.getBindingResult()
                .getFieldErrors()
                .stream()
                .map(fileError -> {
                    Map<String, String> error = new HashMap<>();
                    error.put("field", fileError.getField());
                    error.put("message", fileError.getDefaultMessage());
                    return error;
                })
                .collect(Collectors.toList());

        body.put("errors", errorMessages);
        return new ResponseEntity<>(body, HttpStatus.BAD_REQUEST);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

• @ControllerAdvice
  定义： 是 Spring 框架中用于全局处理控制器（@Controller 或其派生注解如 @RestController）中异常和数据绑定问题的一个特殊注解。
  使用场景： 全局异常处理、数据绑定验证、模型属性添加。

• @ExceptionHandler
  定义： @ExceptionHandler 注解的方法会在目标控制器方法抛出指定异常类型时被调用，用于捕获和处理异常，生成合适的响应结果返回给客户端。

• @ResponseStatus
  定义： 在 @ExceptionHandler 方法上，当该方法处理异常并返回时，应返回的 HTTP 状态码。