Spring 3.1.2文件验证自定义注解失效问题排查

核心问题分析 #

你当前的自定义注解无法触发，主要有三个原因：

1. 验证器类型不匹配：AllowedFileValidator实现的是ConstraintValidator<AllowedFiles, MultipartFile>，仅能验证单个MultipartFile对象，但你把注解标在方法上，Bean Validation无法将方法实例与该验证器关联。
2. 未启用方法级验证支持：Spring默认不会自动触发方法上的Bean Validation注解，需要显式启用。
3. 参数类型不匹配：方法中的文件参数是MultipartFile[]数组，而验证器只处理单个MultipartFile，即便注解生效也无法覆盖数组校验。

两种可行解决方案 #

方案一：用AspectJ切面实现方法级校验（适配你当前的注解位置） #

这种方式直接利用你已引入的AspectJ依赖，不需要修改注解的位置，通过切面拦截标注了@AllowedFiles的方法，手动完成文件校验。

1. 修改验证器类：移除ConstraintValidator实现，转为切面逻辑

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

  @Around("@annotation(allowedFiles)")
  public Object validateFiles(ProceedingJoinPoint joinPoint, AllowedFiles allowedFiles) throws Throwable {
    List<String> allowedTypes = Arrays.asList(allowedFiles.allowedTypes());
    
    // 遍历方法参数，找到MultipartFile[]类型的参数
    for (Object arg : joinPoint.getArgs()) {
      if (arg instanceof MultipartFile[]) {
        MultipartFile[] files = (MultipartFile[]) arg;
        for (MultipartFile file : files) {
          if (!allowedTypes.contains(file.getContentType())) {
            LOGGER.debug("无效文件类型: {}", file.getContentType());
            // 抛出验证异常，可根据需求自定义异常类型
            throw new ConstraintViolationException(allowedFiles.message(), Set.of(
              new ConstraintViolationImpl<>(
                allowedFiles.message(),
                null, null, null, null, null,
                allowedFiles.groups()[0], allowedFiles.payload()[0], null, null
              )
            ));
          }
        }
      }
    }
    // 校验通过，继续执行原方法
    return joinPoint.proceed();
  }
}

2. 修改注解类：移除@Constraint关联，因为现在用切面处理，不需要Bean Validation约束绑定

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.METHOD})
public @interface AllowedFiles {
  String message() default "Invalid File Type";
  Class<?>[] groups() default {};
  Class<? extends Payload>[] payload() default {};
  String [] allowedTypes();
}

3. 启用AspectJ自动代理：在你的Spring配置类上添加@EnableAspectJAutoProxy注解，确保切面生效。

方案二：基于Bean Validation规范实现参数级校验（更符合Spring生态） #

如果可以接受将注解移到参数上，这种方案更简洁，完全遵循Bean Validation规范。

1. 启用方法级验证：在Spring配置类上添加@EnableMethodValidation（Spring 3.0+推荐），同时在Controller类上标注@Validated，确保参数校验生效。

2. 修改验证器类：改为支持MultipartFile[]数组类型

@Component
public class AllowedFileValidator implements ConstraintValidator<AllowedFiles, MultipartFile[]> {
  private static final Logger LOGGER = LoggerFactory.getLogger(AllowedFileValidator.class);
    
  private List<String> allowedFileTypes = new ArrayList<>();
    
  @Override
  public void initialize(AllowedFiles constraintAnnotation) {
    allowedFileTypes = Arrays.asList(constraintAnnotation.allowedTypes());
  }

  @Override
  public boolean isValid(MultipartFile[] files, ConstraintValidatorContext context) {
    LOGGER.debug("进入校验方法");
    if (files == null || files.length == 0) {
      return true; // 可根据业务需求调整是否允许空文件
    }
    for (MultipartFile file : files) {
      if (!allowedFileTypes.contains(file.getContentType())) {
        LOGGER.debug("文件类型无效: {}", file.getContentType());
        // 自定义错误提示
        context.disableDefaultConstraintViolation();
        context.buildConstraintViolationWithTemplate(context.getDefaultConstraintMessageTemplate())
               .addConstraintViolation();
        return false;
      }
    }
    return true;
  }
}

3. 调整Controller方法：将@AllowedFiles注解移到MultipartFile[]参数上

@PostMapping(value = "/createFile", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<ClassName> createFile(
  @Valid @RequestPart("payload") String input,
  @AllowedFiles(
    allowedTypes = {
      "application/x-zip-compressed", "text/csv", "image/bmp", "text/plain", 
      "image/png","image/jpeg", "application/pdf", "application/zip",
      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    }
  ) @RequestPart("file") MultipartFile[] file
) {
  // 业务逻辑
}

额外注意事项 #

• 文件的contentType可能被篡改，建议同时校验文件扩展名作为双重验证。
• Spring 3.1.2中spring-boot-starter-validation已包含所有必要的Bean Validation依赖，无需额外引入其他验证包。
• 若采用切面方案，需确保项目中AspectJ Weaver被正确加载，Spring Boot默认会处理内嵌Tomcat的情况，WAR包部署需确认容器配置。

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