如何为Java List类型应用自定义StringConstraint校验器？

问题背景 #

现有自定义校验注解@StringConstraint及其对应的StringConstraintValidator校验器，可正常校验单个String字段，但需要对请求对象中List<String>类型字段的每个元素应用该校验规则，如何实现？

方案一：利用容器元素校验（推荐，无需新增校验器） #

Hibernate Validator 6.0+（对应Bean Validation 2.0+）支持容器元素校验，只需修改原注解的@Target配置，即可直接对列表泛型元素标注校验：

步骤1：修改@StringConstraint的@Target #

添加ElementType.TYPE_USE，允许注解标注在泛型参数位置：

@Constraint(validatedBy = { StringConstraintValidator.class })
@Documented
@Retention(RetentionPolicy.RUNTIME)
// 新增ElementType.TYPE_USE，支持泛型参数标注
@Target({ ElementType.FIELD, ElementType.PARAMETER, ElementType.TYPE_USE })
public @interface StringConstraint {
    String message() default "'${validatedValue}' 不是有效的格式。字符串需由7个字符组成（数字和大写字母），示例：WBAVD13。";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

步骤2：在List字段上标注泛型校验 #

在List的泛型参数前添加@StringConstraint，同时标注@Valid触发嵌套校验：

@JsonProperty(value = "items", required = true)
@Schema(description = "元素列表", required = true)
@Valid
private List<@StringConstraint String> items = new ArrayList<>();

框架会自动遍历列表中的每个String元素，应用StringConstraintValidator进行校验。

方案二：新增List类型的校验器（兼容低版本） #

如果项目使用的Validator版本不支持容器元素校验，可以新增一个针对List<String>的校验器，并将其添加到@StringConstraint的校验器列表中：

步骤1：实现List的校验器 #

复用单个元素的校验逻辑，避免代码重复：

@Component
public class StringListConstraintValidator implements ConstraintValidator<StringConstraint, List<String>> {

    private final StringConstraintValidator singleValidator;

    @Autowired
    public StringListConstraintValidator(StringConstraintValidator singleValidator) {
        this.singleValidator = singleValidator;
    }

    @Override
    public void initialize(StringConstraint annotation) {
        singleValidator.initialize(annotation);
    }

    @Override
    public boolean isValid(List<String> values, ConstraintValidatorContext context) {
        if (values == null) {
            return false; // 若允许空列表，可调整为return true
        }
        // 遍历校验每个元素
        for (String value : values) {
            if (!singleValidator.isValid(value)) {
                // 自定义错误提示（可选，默认使用原注解message）
                context.disableDefaultConstraintViolation();
                context.buildConstraintViolationWithTemplate(
                        String.format("元素'%s'不符合格式要求", value)
                ).addConstraintViolation();
                return false;
            }
        }
        return true;
    }
}

步骤2：更新@StringConstraint的校验器列表 #

将新增的校验器加入validatedBy数组：

@Constraint(validatedBy = { StringConstraintValidator.class, StringListConstraintValidator.class })
// 其余注解配置不变
public @interface StringConstraint {
    // ... 原有内容
}

步骤3：在List字段上直接标注注解 #

@JsonProperty(value = "items", required = true)
@Schema(description = "元素列表", required = true)
@StringConstraint
private List<String> items = new ArrayList<>();

注意事项 #

• 方案一中，若需控制列表本身的非空性，需额外添加@NotEmpty或@NotNull注解；
• 方案二中，可根据需求调整空列表的校验逻辑；
• 确保项目已正确配置Bean Validation生效逻辑（如Spring项目启用@Validated）。

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