Spring Boot中@NotNull验证MultipartFile字段失效问题排查

核心原因：@NotNull 对 MultipartFile 的局限性 #

表单提交时，即便用户未选择文件，Spring MVC 也会创建一个空的 MultipartFile 实例（而非 null），这个实例的 isEmpty() 方法返回 true，但对象本身不为 null。而 @NotNull 仅校验对象是否为 null，因此无法识别这种“空文件”的场景；如果上传了文件仍触发异常，大概率是表单字段名与实体类的 documentFile 字段名不匹配，导致 Spring 无法正确绑定，字段值为 null 触发了 @NotNull 校验。

可行的校验方案 #

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

针对 MultipartFile 专门实现非空校验，能精准判断是否上传了有效文件：

1. 定义校验注解

import jakarta.validation.Constraint
import jakarta.validation.Payload
import kotlin.reflect.KClass

@Target(AnnotationTarget.FIELD)
@Retention(AnnotationRetention.RUNTIME)
@Constraint(validatedBy = [FileNotEmptyValidator::class])
annotation class FileNotEmpty(
    val message: String = "文件不能为空",
    val groups: Array<KClass<*>> = [],
    val payload: Array<KClass<out Payload>> = []
)

2. 实现校验器

import jakarta.validation.ConstraintValidator
import jakarta.validation.ConstraintValidatorContext
import org.springframework.web.multipart.MultipartFile

class FileNotEmptyValidator : ConstraintValidator<FileNotEmpty, MultipartFile> {
    override fun isValid(value: MultipartFile?, context: ConstraintValidatorContext): Boolean {
        // 校验逻辑：对象非空且不是空文件
        return value != null && !value.isEmpty
    }
}

3. 在实体类中使用

import jakarta.persistence.Entity
import jakarta.persistence.Transient
import org.springframework.web.multipart.MultipartFile

@Entity
class Document {
    // 其他实体字段...

    @field:FileNotEmpty
    @Transient
    var documentFile: MultipartFile? = null
}

方案2：使用 @AssertTrue 做方法级校验 #

无需自定义注解，通过实体类中的方法结合 @AssertTrue 实现校验：

import jakarta.persistence.Entity
import jakarta.persistence.Transient
import jakarta.validation.constraints.AssertTrue
import org.springframework.web.multipart.MultipartFile

@Entity
class Document {
    // 其他实体字段...

    @Transient
    var documentFile: MultipartFile? = null

    @AssertTrue(message = "文件不能为空")
    fun isDocumentFileValid(): Boolean {
        return documentFile != null && !documentFile!!.isEmpty
    }
}

方案3：改用 @RequestParam 单独接收文件 #

如果不需要绑定到实体类，直接在控制器方法中单独接收文件，结合 Spring 的校验机制：

import jakarta.validation.constraints.NotNull
import org.springframework.validation.annotation.Validated
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestParam
import org.springframework.web.bind.annotation.RestController
import org.springframework.web.multipart.MultipartFile

@RestController
@Validated // 开启Spring方法级校验
class DocumentController {

    @PostMapping("/upload")
    fun upload(@RequestParam("documentFile") @NotNull(message = "文件不能为空") file: MultipartFile) {
        // 业务逻辑
    }
}

额外注意事项 #

1. 确保表单中的文件输入框 name 属性与实体类字段名一致，比如 <input type="file" name="documentFile">，否则 Spring 无法正确绑定字段值。
2. 控制器方法中使用 @Valid @ModelAttribute 或 @Validated @ModelAttribute 时，需确保实体类的校验注解导入的是 jakarta.validation 包下的（Spring Boot 3.x 统一使用 Jakarta 规范）。

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