Spring Boot中如何校验请求体里的枚举参数合法性？

针对你在REST API请求体中校验枚举参数的需求，以下是几种实用的解决方案：

方案一：自定义校验注解（推荐） #

这种方式灵活性最高，枚举值变更时无需修改校验逻辑，适合长期维护的项目。

1. 定义自定义校验注解 #

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.*;

@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = EnumValueValidator.class)
@Documented
public @interface EnumValue {
    String message() default "输入值不在有效范围内";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
    // 指定要校验的枚举类
    Class<? extends Enum<?>> enumClass();
}

2. 实现校验器逻辑 #

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import java.util.Arrays;

public class EnumValueValidator implements ConstraintValidator<EnumValue, String> {
    private Enum<?>[] enumConstants;

    @Override
    public void initialize(EnumValue constraintAnnotation) {
        // 初始化时获取枚举的所有有效值
        this.enumConstants = constraintAnnotation.enumClass().getEnumConstants();
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        // 允许null的情况（如果要强制非空，配合@NotBlank/@NotNull使用）
        if (value == null) {
            return true;
        }
        // 校验输入值是否匹配枚举中的任意有效值
        return Arrays.stream(enumConstants)
                .anyMatch(enumItem -> enumItem.name().equals(value));
    }
}

3. 在DTO中使用注解 #

public class CarDto {
    // 结合@NotBlank强制非空，@EnumValue校验枚举有效值
    @NotBlank(message = "level不能为空")
    @EnumValue(enumClass = Level.class, message = "level只能是NEW或OLD")
    private String level;

    // 也可以直接用枚举类型接收，此时Spring会自动转换，转换失败抛异常
    // @NotNull(message = "level不能为空")
    // private Level level;
}

方案二：使用@Pattern注解（简单场景） #

如果枚举值固定、不会频繁变更，可以直接用正则表达式匹配有效值，实现成本最低：

public class CarDto {
    @NotBlank(message = "level不能为空")
    @Pattern(regexp = "^(NEW|OLD)$", message = "level只能是NEW或OLD")
    private String level;
}

缺点：枚举值修改时必须同步更新正则表达式，维护成本较高。

方案三：全局异常处理（配合Spring自动转换） #

如果DTO中直接使用Level枚举类型，Spring在接收请求时会自动尝试将字符串转换为枚举实例，转换失败会抛出MethodArgumentTypeMismatchException。我们可以通过全局异常处理器统一捕获并返回友好提示：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentTypeMismatchException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import java.util.Arrays;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    public ResponseEntity<String> handleEnumMismatch(MethodArgumentTypeMismatchException e) {
        if (e.getRequiredType() != null && e.getRequiredType().isEnum()) {
            // 拼接枚举的所有有效值
            String validValues = Arrays.stream(e.getRequiredType().getEnumConstants())
                    .map(Object::toString)
                    .reduce((a, b) -> a + ", " + b)
                    .orElse("");
            String errorMsg = String.format("参数「%s」的值无效，有效值为：%s", e.getName(), validValues);
            return new ResponseEntity<>(errorMsg, HttpStatus.BAD_REQUEST);
        }
        return new ResponseEntity<>("参数格式错误", HttpStatus.BAD_REQUEST);
    }
}

这样当用户输入非枚举有效值时，会收到类似参数「level」的值无效，有效值为：NEW, OLD的响应。

内容的提问来源于stack exchange，提问作者jack nik