SpringBoot自定义枚举类型参数校验

背景

在实际的开发中，许多接口的入参我们都是用自定义枚举来定义，比如性别，币种，订单类型等等，服务端一般都需要保证这些参数的正确性，如果使用编码来处理，那么项目中会有很多if-else的代码，整体的维护性和可读性都不高，针对这种情况我们可以使用自定义注解来统一处理。

 使用spring-boot-starter-validation来处理

一、引入pom依赖

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

 二、自定义枚举和Validator

package com.rome.trade.common.annotation;
import jakarta.validation.Constraint;
import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;
import jakarta.validation.Payload;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;


import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.util.Objects;


@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = EnumValueValidator.Validator.class)
public @interface EnumValueValidator {

    String message() default "参数有误";

    Class<? extends Enum<?>> enumClass();

    String enumMethod();

    Class<?>[] groups() default { };

    Class<? extends Payload>[] payload() default {};

    @Slf4j
    class Validator implements ConstraintValidator<EnumValueValidator, Object> {
        private Class<? extends Enum<?>> enumClass;
        private String enumMethod;

        @Override
        public void initialize(EnumValueValidator constraintAnnotation) {
            enumMethod = constraintAnnotation.enumMethod();
            enumClass = constraintAnnotation.enumClass();
        }

        @Override
        public boolean isValid(Object o, ConstraintValidatorContext constraintValidatorContext) {
            if (Objects.isNull(o)) {
                return Boolean.TRUE;
            }
            if (enumClass == null || StringUtils.isBlank(enumMethod)) {
                return Boolean.TRUE;
            }
            Class<?> vclass = o.getClass();
            try {
                Method method = enumClass.getMethod(enumMethod, vclass);
                if (!Boolean.TYPE.equals(method.getReturnType()) &&
                        !Boolean.class.equals(method.getReturnType())) {
                    throw new RuntimeException("校验方法不是布尔类型!");
                }
                if (!Modifier.isStatic(method.getModifiers())) {
                    throw new RuntimeException("校验方法不是静态方法!");
                }
                method.setAccessible(true);

                Boolean res = (Boolean) method.invoke(null, o);
                return res != null ? res : false;
            } catch (NoSuchMethodException e) {
                log.error("NoSuchMethodException:", e);
                throw new RuntimeException(e);
            } catch (IllegalAccessException e) {
                log.error("IllegalAccessException:", e);
                throw new RuntimeException(e);
            } catch (InvocationTargetException e) {
                log.error("InvocationTargetException:", e);
                throw new RuntimeException(e);
            }
        }
    }
}

三、使用 @ControllerAdvice对校验异常处理

package com.rome.trade.common.config;

import cn.hutool.core.collection.CollUtil;
import com.rome.trade.common.enums.ResultEnum;
import com.rome.trade.common.vo.Result;
import lombok.extern.slf4j.Slf4j;
import org.springframework.validation.ObjectError;
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.ResponseBody;

import java.util.List;

@ControllerAdvice
@Slf4j
public class ControllerAdviceConfig {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseBody
    public Result<Void> handleMethodArgumentNotValidException(MethodArgumentNotValidException e) {
        log.error("==>参数不合法:", e);
        List<ObjectError> errorList = e.getBindingResult().getAllErrors();
        if (CollUtil.isEmpty(errorList)) {
            return Result.fail(ResultEnum.PARAMS_ERROR.getCode(), ResultEnum.PARAMS_ERROR.getMessage());
        }
        ObjectError objectError = errorList.get(0);
        return Result.fail(ResultEnum.PARAMS_ERROR.getCode(), objectError.getDefaultMessage());

    }


}

项目中的实际应用

一、定义我们的业务枚举

package com.rometrade.api.enums;

import com.rome.trade.common.enums.ResultEnum;
import com.rome.trade.common.exception.BusinessException;
import com.rometrade.api.enums.statemachine.zy_fk_001.ZYFK001Event;
import com.rometrade.api.enums.statemachine.zy_fk_001.ZYFK001State;
import com.rometrade.api.enums.statemachine.zy_hk_001.ZYHK001Event;
import com.rometrade.api.enums.statemachine.zy_hk_001.ZYHK001State;
import lombok.AllArgsConstructor;
import lombok.Getter;
import org.apache.commons.lang3.StringUtils;

import java.util.Arrays;

/**
 * @author shilei
 */

@Getter
@AllArgsConstructor
public enum TradeCodeEnum {

    ZY_FK_001("ZY_FK_001", "zyfk001StateMachine", "zyfk001TradeOrderCheckServiceImpl", ZYFK001State.INIT, ZYFK001Event.PROCESSING),

    ZY_HK_001("ZY_HK_001", "zyhk001StateMachine", "zyhk001TradeOrderCheckServiceImpl", ZYHK001State.INIT, ZYHK001Event.PROCESSING);

    private final String stateMachineId;
    private final String beanName;
    private final String checkName;
    private final Enum stateEnum;
    private final Enum eventEnum;

    public static TradeCodeEnum getTradeCodeEnum(String code) {
        return Arrays.stream(TradeCodeEnum.values()).filter(o -> o.name().equals(code)).findFirst()
                .orElseThrow(() -> new BusinessException(ResultEnum.NO_TRADE_CODE));
    }

    /**
     * 此方法是重点，Validator会调用这个方法来判断参数是否匹配
     */
    public static boolean isValueValid(String value) {
        if (StringUtils.isNotBlank(value)) {
            for (TradeCodeEnum enums : TradeCodeEnum.values()) {
                if (enums.getStateMachineId().equals(value)) {
                    return true;
                }
            }
            return false;
        }
        return true;
    }
}

 二、定义接口入参

 tradeCode参数会使用自定义的枚举：@EnumValueValidator

package com.rometrade.api.dto;

import com.fasterxml.jackson.annotation.JsonFormat;
import com.rome.trade.common.annotation.EnumValueValidator;
import com.rometrade.api.enums.TradeCodeEnum;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import lombok.Data;

import java.io.Serial;
import java.io.Serializable;
import java.time.LocalDateTime;

/**
 * @author shilei
 */
@Data
public class CreateOrderDTO implements Serializable {
    @Serial
    private static final long serialVersionUID = -4594510930327388073L;

    @Schema(description = "交易单号")
    private String tradeNo;

    @Schema(description = "业务订单号")
    @NotBlank(message = "业务订单号不能为空")
    private String businessOrderNo;

    @Schema(description = "客户id")
    @NotNull(message = "客户id不能为空")
    private Long customerId;

    @Schema(description = "交易码")
    @NotBlank(message = "交易码不能为空")
    @EnumValueValidator(enumClass = TradeCodeEnum.class, enumMethod = "isValueValid", message = "交易码有误")
    private String tradeCode;

    @Schema(description = "交易参数")
    private String tradeParam;

    @Schema(description = "支付参数")
    private String paymentParam;

    @Schema(description = "核算参数")
    private String billingParam;

    @Schema(description = "附件参数")
    private String otherParam;

    @Schema(description = "产品编码")
    private String productCode;

    @Schema(description = "渠道编码")
    @NotBlank(message = "渠道编码不能为空")
    private String channelCode;

    @Schema(description = "交易时间")
    @NotNull(message = "交易时间不能为空")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private LocalDateTime tradeTime;

}

三、编写接口controller

package com.rome.trade.core.controller;

import com.rome.trade.common.vo.Result;
import com.rome.trade.core.service.TradeOrderService;
import com.rometrade.api.dto.CreateOrderDTO;
import com.rometrade.api.vo.TradeOrderVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;


/**
 * @author shilei
 */
@RestController
@RequestMapping("/order")
@RequiredArgsConstructor
@Slf4j
@Tag(name = "交易单API", description = "交易单API")
public class TradeOrderController {
    private final TradeOrderService tradeOrderService;

    @PostMapping("/create")
    @Operation(summary = "交易收单接口")
    public Result<TradeOrderVO> createOrder(@Valid @RequestBody CreateOrderDTO createOrderDTO) {
        return Result.success(tradeOrderService.createOrder(createOrderDTO));
    }
}

 四、校验测试