SpringBoot中自定义注解实现参数非空校验

SpringBoot中自定义注解实现参数非空校验

前言

由于刚写项目不久,在写 web 后台接口时,经常会对前端传入的参数进行一些规则校验,如果入参较少还好,一旦需要校验的参数比较多,那么使用 if 校验会带来大量的重复性工作,并且代码看起来会非常冗余,所以我首先想到能否通过一些手段改进这点,让 Controller 层减少参数校验的冗余代码,提升代码的可阅读性。

经过阅读他人的代码,发现使用 annotation 注解是一个比较方便的手段,SpringBoot 自带的 @RequestParam 注解只会校验请求中该参数是否存在,但是该参数是否符合一些规格比如不为 null 且不为空就无法进行判断的,所以我们可以尝试一下增强请求参数中的注解。

准备工作

有了前面的思路,我们先搭一个架子出来。

  • SpringBoot 2.3.5.REALEASE
  • JDK 1.8

pom.xml 文件如下:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.3.5.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>cn.bestzuo</groupId>
    <artifactId>springboot-annotation</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-annotation</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <!--引入AOP相应的注解-->
        <dependency>
            <groupId>org.aspectj</groupId>
            <artifactId>aspectjweaver</artifactId>
            <version>1.8.5</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

其中 aspectjweaver 用于引入 AOP 的相关的注解,如 @Aspect@Pointcut 等.

使用自定义注解实现统一非空校验

总体思路:自定义一个注解,对必填的参数加上该注解,然后定义一个切面,校验该参数是否为空,如果为空则抛出自定义的异常,该异常被自定义的异常处理器捕获,然后返回相应的错误信息。

1.自定义注解

创建一个名为 ParamCheck 的注解,代码如下:

package cn.bestzuo.springbootannotation.annotation;

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

/**
 * 参数不能为空注解,作用于方法参数上
 *
 * @author zuoxiang
 * @since 2020-11-11
 */
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface ParamCheck {
    /**
     * 是否非空,默认不能为空
     */
    boolean notNull() default true;
}

其中 @Target 注解中的 ElementType.PARAMETER 表示该注解的作用范围,我们查看源码可以看到,注解的作用范围定义比较广泛,可以作用于方法、参数、构造方法、本地变量、枚举等等。

public enum ElementType {
    /** Class, interface (including annotation type), or enum declaration */
    TYPE,

    /** Field declaration (includes enum constants) */
    FIELD,

    /** Method declaration */
    METHOD,

    /** Formal parameter declaration */
    PARAMETER,

    /** Constructor declaration */
    CONSTRUCTOR,

    /** Local variable declaration */
    LOCAL_VARIABLE,

    /** Annotation type declaration */
    ANNOTATION_TYPE,

    /** Package declaration */
    PACKAGE,

    /**
     * Type parameter declaration
     *
     * @since 1.8
     */
    TYPE_PARAMETER,

    /**
     * Use of a type
     *
     * @since 1.8
     */
    TYPE_USE
}

当然,我们定义的注解可以扩展,不仅仅去校验参数是否为空,比如我们可以增加字符串长度的校验。

2.自定义异常类

我们在这里自定义异常的原因,是为了配合自定义注解使用,一旦校验出不符合我们自定义注解规格的参数,可以直接抛出自定义异常返回。代码如下:

package cn.bestzuo.springbootannotation.exception;

public class ParamIsNullException extends RuntimeException {
    private final String parameterName;
    private final String parameterType;

    public ParamIsNullException(String parameterName, String parameterType) {
        super("");
        this.parameterName = parameterName;
        this.parameterType = parameterType;
    }

    /**
     * 重写了该方法
     *
     * @return 异常消息通知
     */
    @Override
    public String getMessage() {
        return "Required " + this.parameterType + " parameter \'" + this.parameterName + "\' must be not null !";
    }

    public final String getParameterName() {
        return this.parameterName;
    }

    public final String getParameterType() {
        return this.parameterType;
    }
}
  • 该异常继承 RuntimeException,并定义了两个成员属性、重写了 getMessage() 方法
  • 之所以自定义该异常,而不用现有的 org.springframework.web.bind.MissingServletRequestParameterException 类,是因为 MissingServletRequestParameterException为Checked 异常,在动态代理过程中,很容易引发 java.lang.reflect.UndeclaredThrowableException 异常。

3.自定义 AOP

代码如下:

package cn.bestzuo.springbootannotation.aop;

import cn.bestzuo.springbootannotation.annotation.ParamCheck;
import cn.bestzuo.springbootannotation.exception.ParamIsNullException;
import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.*;
import org.aspectj.lang.reflect.MethodSignature;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

import java.lang.annotation.Annotation;
import java.lang.reflect.Method;

@Component
@Aspect
public class ParamCheckAop {
    private static final Logger LOGGER = LoggerFactory.getLogger(ParamCheckAop.class);

    /**
     * 定义有一个切入点,范围为 controller 包下的类
     */
    @Pointcut("execution(public * cn.bestzuo.controller..*.*(..))")
    public void checkParam() {

    }

    @Before("checkParam()")
    public void doBefore(JoinPoint joinPoint) {
    }

    /**
     * 检查参数是否为空
     *
     * @param pjp 连接点
     * @return 对象
     * @throws Throwable 异常
     */
    @Around("checkParam()")
    public Object doAround(ProceedingJoinPoint pjp) throws Throwable {
        MethodSignature signature = ((MethodSignature) pjp.getSignature());
        //得到拦截的方法
        Method method = signature.getMethod();
        //获取方法参数注解,返回二维数组是因为某些参数可能存在多个注解
        Annotation[][] parameterAnnotations = method.getParameterAnnotations();
        if (parameterAnnotations.length == 0) {
            return pjp.proceed();
        }
        //获取方法参数名
        String[] paramNames = signature.getParameterNames();
        //获取参数值
        Object[] paramValues = pjp.getArgs();
        //获取方法参数类型
        Class<?>[] parameterTypes = method.getParameterTypes();
        for (int i = 0; i < parameterAnnotations.length; i++) {
            for (int j = 0; j < parameterAnnotations[i].length; j++) {
                //如果该参数前面的注解是ParamCheck的实例,并且notNull()=true,则进行非空校验
                if (parameterAnnotations[i][j] != null && parameterAnnotations[i][j] instanceof ParamCheck && ((ParamCheck) parameterAnnotations[i][j]).notNull()) {
                    paramIsNull(paramNames[i], paramValues[i], parameterTypes[i] == null ? null : parameterTypes[i].getName());
                    break;
                }
            }
        }
        return pjp.proceed();
    }

    /**
     * 在切入点return内容之后切入内容(可以用来对处理返回值做一些加工处理)
     *
     * @param joinPoint 连接点
     */
    @AfterReturning("checkParam()")
    public void doAfterReturning(JoinPoint joinPoint) {
    }

    /**
     * 参数非空校验,如果参数为空,则抛出ParamIsNullException异常
     *
     * @param paramName     参数名称
     * @param value         参数值
     * @param parameterType 参数类型
     */
    private void paramIsNull(String paramName, Object value, String parameterType) {
        if (value == null || "".equals(value.toString().trim())) {
            throw new ParamIsNullException(paramName, parameterType);
        }
    }
}

4.全局异常处理器

该异常处理器捕获在 ParamCheckAop 类中抛出的 ParamIsNullException 异常,并进行处理,代码如下:

import cn.bestzuo.springbootannotation.common.Result;
import cn.bestzuo.springbootannotation.enums.EnumResultCode;
import cn.bestzuo.springbootannotation.utils.ResponseMsgUtil;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.MissingServletRequestParameterException;
import org.springframework.web.bind.annotation.ExceptionHandler;

import javax.servlet.http.HttpServletRequest;

public class GlobalExceptionHandler {
    private static final Logger LOGGER = LoggerFactory.getLogger(GlobalExceptionHandler.class);


    /**
     * 参数为空异常处理
     *
     * @param ex 异常
     * @return 返回的异常
     */
    @ExceptionHandler({MissingServletRequestParameterException.class, ParamIsNullException.class})
    public Result<String> requestMissingServletRequest(Exception ex) {
        LOGGER.error("request Exception:", ex);
        return ResponseMsgUtil.builderResponse(EnumResultCode.FAIL.getCode(), ex.getMessage(), null);
    }

    /**
     * 特别说明: 可以配置指定的异常处理,这里处理所有
     *
     * @param request 请求
     * @param e       异常体
     * @return 返回的异常
     */
    @ExceptionHandler(value = Exception.class)
    public Result<String> errorHandler(HttpServletRequest request, Exception e) {
        LOGGER.error("request Exception:", e);
        return ResponseMsgUtil.exception();
    }
}

5.测试

首先定义一个 Controller 进行测试:

@RestController
public class HelloController {
    /**
     * 测试@RequestParam注解
     *
     * @param name 测试参数
     * @return 包装结果
     */
    @GetMapping("/hello1")
    public Result<String> hello1(@RequestParam String name) {
        return ResponseMsgUtil.builderResponse(EnumResultCode.SUCCESS.getCode(), "请求成功", "Hello," + name);
    }

    /**
     * 测试@ParamCheck注解
     *
     * @param name 测试参数
     * @return 包装结果
     */
    @GetMapping("/hello2")
    public Result<String> hello2(@ParamCheck String name) {
        return ResponseMsgUtil.builderResponse(EnumResultCode.SUCCESS.getCode(), "请求成功", "Hello," + name);
    }

    /**
     * 测试@ParamCheck与@RequestParam一起时
     *
     * @param name 测试参数
     * @return 包装结果
     */
    @GetMapping("/hello3")
    public Result<String> hello3(@ParamCheck @RequestParam String name) {
        return ResponseMsgUtil.builderResponse(EnumResultCode.SUCCESS.getCode(), "请求成功", "Hello," + name);
    }
}

测试访问 http://localhost:8080/hello1,此时只有 @RequestParam 注解,如果不加 name 参数,会请求得到一个异常:

image.png

并且控制台会报 MissingServletRequestParameterException: Required String parameter 'name' is not present] 异常

如果访问 http://localhost:8080/hello2?name=,此时使用的是我们自定义的 @ParamCheck 注解,此时没有参数输入,那么也会捕获输入的异常:

image.png

如果访问 http://localhost:8080/hello3?name=,此时既有参数存在校验,又有我们自定义的 ParamCheck 不为空校验,所以此时访问不加参数会抛出异常:

image.png

控制台抛出我们自定义的异常:

image.png

测试总结:

  1. 当参数名为空时,分别添加两个注解的接口都会提示参数不能为空
  2. 当参数名不为空,值为空时,@RequestParam注解不会报错,但@ParamCheck注解提示参数'name'的值为空

6.总结

  1. 经过以上的测试也验证了 @RequestParam 只会验证对应的参数是否存在,而不会验证值是否为空
  2. ParamCheck 还可以进行拓展,比如参数值长度、是否含有非法字符等校验

7.代码附录

上述使用到的代码:

package cn.bestzuo.springbootannotation.common;

import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class Result<T> {
    private Integer resCode;
    private String resMsg;
    private T data;
}
package cn.bestzuo.springbootannotation.enums;

/**
 * 枚举参数结果
 *
 * @author zuoxiang
 * @since 2020-11-11
 */
public enum EnumResultCode {
    SUCCESS(200),

    FAIL(400),

    UNAUTHORIZED(401),

    NOT_FOUND(404),

    INTERNAL_SERVER_ERROR(500);

    private final int code;

    EnumResultCode(int code) {
        this.code = code;
    }

    public int getCode() {
        return code;
    }
}
package cn.bestzuo.springbootannotation.utils;

import cn.bestzuo.springbootannotation.common.Result;
import cn.bestzuo.springbootannotation.enums.EnumResultCode;

public class ResponseMsgUtil {
    /**
     * 根据消息码等生成接口返回对象
     *
     * @param code 结果返回码
     * @param msg  结果返回消息
     * @param data 数据对象
     * @param <T>  泛型
     * @return 包装对象
     */
    public static <T> Result<T> builderResponse(int code, String msg, T data) {
        Result<T> res = new Result<>();
        res.setResCode(code);
        res.setResMsg(msg);
        res.setData(data);
        return res;
    }

    /**
     * 请求异常返回结果
     *
     * @param <T> 泛型
     * @return 包装对象
     */
    public static <T> Result<T> exception() {
        return builderResponse(EnumResultCode.INTERNAL_SERVER_ERROR.getCode(), "服务异常", null);
    }
}

参考文章

  1. 使用SpringBoot通过自定义注解+AOP+全局异常处理实现参数统一非空校验

本文由 Sanarous 创作,如果您觉得本文不错,请随意赞赏
采用 知识共享署名4.0 国际许可协议进行许可,转载前请务必署名
本文链接:https://bestzuo.cn/posts/springboot-annotation-notnull.html
最后更新于:2020-11-11 21:03:00

切换主题 | SCHEME TOOL  
>