一、 背景与痛点
在 Spring Boot 后端开发中，我们经常遇到需要前端传递“状态码”、“类型”或“场景码”的情况。这些值在后端通常对应一个枚举（Enum）。
例如，发送短信的场景（scene）：
1: 登录2: 忘记密码3: 注册
痛点在于：如果前端传了一个99（不存在的场景），或者传了一个非法的数字，如果后端只用了@NotNull，这个非法值会穿透 Controller 进入 Service 层，导致业务逻辑报错（如空指针）或者产生脏数据。
我们需要一个机制：像保安一样，手里拿着一份“白名单”，只有在枚举范围内定义过的值，才允许通过。
本文将带你实现一个高性能的自定义注解@InEnum。
二、 核心架构设计
为了实现通用且高性能的校验，我们需要三个组件配合：
- 接口 (
ArrayValuable)：定义统一的规范，要求枚举类必须提供一个“返回所有合法值”的方法。 - 注解 (
@InEnum)：标注在 DTO 字段上，指定使用哪个枚举类作为白名单。 - 校验器 (
InEnumValidator)：执行具体的校验逻辑。
1. 定义统一接口
为了让校验器能读懂所有的枚举，我们需要定义一个接口。
publicinterfaceArrayValuable<T>{/** * @return 返回枚举中所有合法的数值集合 */T[]array();}2. 定义注解 @InEnum
这是 JSR-303 标准的自定义注解写法。
@Target({ElementType.METHOD,ElementType.FIELD,ElementType.PARAMETER})@Retention(RetentionPolicy.RUNTIME)@Documented@Constraint(validatedBy=InEnumValidator.class)// 指定校验器public@interfaceInEnum{/** * @return 必须传入实现 ArrayValuable 接口的枚举类 */Class<?extendsArrayValuable<?>>value();Stringmessage()default"必须在指定范围 {value}";Class<?>[]groups()default{};Class<?extendsPayload>[]payload()default{};}关键点解析：
Class<? extends ArrayValuable<?>> value();：这里利用泛型限定，强制要求使用该注解时，传入的 Class 必须是实现了ArrayValuable接口的类。这在编译期就杜绝了乱传 Class 的可能。
3. 实现校验器 InEnumValidator
这是“执法者”，负责初始化白名单并进行比对。
publicclassInEnumValidatorimplementsConstraintValidator<InEnum,Object>{// 缓存白名单，避免每次校验都去反射计算privateList<?>values;@Overridepublicvoidinitialize(InEnumannotation){// 1. 获取注解传入的枚举类的所有实例，value()返回的就是实现了ArrayValuable接口的类// getEnumConstants()返回的就是实现类中的所有枚举类型ArrayValuable<?>[]constants=annotation.value().getEnumConstants();if(constants.length==0){this.values=Collections.emptyList();}else{// 2. 【核心】随便拿第一个实例，调用接口的 array() 方法拿到白名单// 利用了接口多态性，根本不需要关心具体是哪个 Enumthis.values=Arrays.asList(constants[0].array());}}@OverridepublicbooleanisValid(Objectvalue,ConstraintValidatorContextcontext){// Object value指的是@Inenum标注的字段，也就是前端传入的// 1. 判空放行：非空校验交给 @NotNull 处理，保持职责单一if(value==null){returntrue;}// 2. 校验通过：值在白名单内if(values.contains(value)){returntrue;}// 3. 校验失败：自定义友好的报错信息// 禁用默认提示，改写为："必须在指定范围 [1, 2, 3]"context.disableDefaultConstraintViolation();context.buildConstraintViolationWithTemplate(context.getDefaultConstraintMessageTemplate().replaceAll("\\{value}",values.toString())).addConstraintViolation();returnfalse;}}三、 最佳实践案例：SmsSceneEnum
有了基础设施，我们来看看在业务中如何优雅地使用。这里展示一个高性能的枚举写法。
1. 编写枚举类
@Getter@AllArgsConstructorpublicenumSmsSceneEnumimplementsArrayValuable<Integer>{MEMBER_LOGIN(1,"user-sms-login","会员用户 - 手机号登陆"),MEMBER_UPDATE_MOBILE(2,"user-update-mobile","会员用户 - 修改手机"),MEMBER_UPDATE_PASSWORD(3,"user-update-password","会员用户 - 修改密码"),// ... 其他枚举值ADMIN_MEMBER_LOGIN(21,"admin-sms-login","后台用户 - 手机号登录");// 【性能黑科技】// 在类加载时，就利用 Stream 流计算好所有合法的 scene 值，存入静态数组。// 避免了每次调用 array() 方法都要去遍历 values()，极大提升性能。publicstaticfinalInteger[]ARRAYS=Arrays.stream(values()).map(SmsSceneEnum::getScene).toArray(Integer[]::new);privatefinalIntegerscene;privatefinalStringtemplateCode;privatefinalStringdescription;// 实现接口方法，直接返回计算好的静态数组@OverridepublicInteger[]array(){returnARRAYS;}// ... getCodeByScene 等其他方法}2. 在 DTO 中使用
@DatapublicclassSmsSendReqVO{@Schema(description="手机号",requiredMode=Schema.RequiredMode.REQUIRED)@Mobile// 假设有一个手机号格式校验注解privateStringmobile;@Schema(description="发送场景",requiredMode=Schema.RequiredMode.REQUIRED,example="1")@NotNull(message="发送场景不能为空")// 👇 一行代码搞定白名单校验@InEnum(value=SmsSceneEnum.class,message="发送场景必须是 {value}")privateIntegerscene;}四、 运行原理深度解析
当前端请求接口时，整个校验流程如下：
Spring 启动/首次调用时：
InEnumValidator的initialize方法被触发。- 它拿到
SmsSceneEnum.class。 - 它获取
SmsSceneEnum的第一个实例MEMBER_LOGIN。 - 它调用
MEMBER_LOGIN.array()。 - 关键点：
array()方法直接返回了SmsSceneEnum中预先计算好的static final ARRAYS([1, 2, 3, 21])。 - Validator 将这个 List 存入内存
this.values。
前端请求到来 (
scene = 99)：- 进入
isValid方法。 - 判断
values.contains(99)。 - 结果为
false。 - 拦截请求，抛出异常。
- 前端收到错误提示：
"发送场景必须是 [1, 2, 3, 21]"。
- 进入
