Kotlin Spring Boot：@PutMapping接收List<数据类>时@Valid验证失效

问题分析 #

Spring Boot默认不会自动触发对集合类型（如List）请求体的验证，即使你在泛型上标注@Valid，也需要配合类级别的注解开启方法级验证，才能让集合内的每个元素都触发校验。

解决方案步骤 #

1. 给控制器类添加@Validated注解 #

这个注解是Spring提供的，用于开启方法参数的验证支持，是集合验证生效的关键。

@RestController
@Validated // 必须添加此注解
class DataController {

    @PutMapping("/batch-update")
    fun batchUpdate(@Valid @RequestBody upsertDataList: List<@Valid UpsertData>): ResponseEntity<String> {
        // 执行业务逻辑
        return ResponseEntity.ok("批量更新成功")
    }
}

2. 确保数据类的校验注解正确 #

你的数据类已经使用了@field:前缀指定注解目标为字段，这是Kotlin中正确的写法，保持即可：

data class UpsertData(
    @field:NotBlank(message = "Name must not be blank")
    val naName: String,
    @field:Min(value = 18, message = "Age must be at least 18")
    val age: Int
)

3. 全局捕获验证异常（可选但推荐） #

添加全局异常处理器，将验证失败的信息友好返回给前端：

@RestControllerAdvice
class ValidationErrorHandler {

    // 处理集合类型参数的验证异常
    @ExceptionHandler(ConstraintViolationException::class)
    fun handleConstraintViolation(ex: ConstraintViolationException): ResponseEntity<Map<String, String>> {
        val errorMap = ex.constraintViolations.associate {
            // 提取验证失败的路径和提示信息
            it.propertyPath.toString().replaceFirst("\\[\\d+\\]", "") to it.message
        }
        return ResponseEntity.badRequest().body(errorMap)
    }

    // 处理单个Bean的验证异常（保留兼容）
    @ExceptionHandler(MethodArgumentNotValidException::class)
    fun handleMethodArgumentNotValid(ex: MethodArgumentNotValidException): ResponseEntity<Map<String, String>> {
        val errorMap = ex.bindingResult.fieldErrors.associate {
            it.field to it.defaultMessage ?: "参数格式错误"
        }
        return ResponseEntity.badRequest().body(errorMap)
    }
}

关键原理 #

• @Validated：开启控制器的方法级验证能力，让Spring能够识别并处理方法参数上的校验规则。
• @Valid @RequestBody List<@Valid UpsertData>：外层@Valid触发对整个集合的验证逻辑，泛型中的@Valid指定集合内的每个UpsertData对象都要执行字段校验。

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