Bean Validation API: anotaciones @NotNull, @Min, @Max, etc.

"En un mundo ideal, todos los usuarios enviarían solo datos correctos..." — suena como el inicio de un cuento. En la realidad nos topamos con errores tipográficos en formularios, campos obligatorios olvidados e incluso intentos de SQL injections en el campo del nombre. Aquí entra en escena la validación de datos: la primera línea de defensa de cualquier aplicación web.

En la última clase mencionamos de pasada Bean Validation API — un conjunto de anotaciones especiales que convierten la validación de datos de un dolor de cabeza a un proceso simple y claro. Ahora vamos a conocerlo con más detalle.

¿Qué es Bean Validation API?

Bean Validation API — es una especificación de Java (JSR 380) que proporciona un conjunto de anotaciones para definir reglas de validación. Funciona en conjunto con Hibernate Validator, que a menudo se usa como la implementación de esta especificación en aplicaciones Spring.

Bean Validation permite validar:

• Campos de objetos (por ejemplo, entidades de base de datos o DTO).
• Parámetros de entrada de métodos.
• Configuraciones de clases.

Un ejemplo clásico de validación: necesitas asegurarte de que el usuario no dejó el campo "email" vacío y lo introdujo en el formato correcto. En vez de escribir comprobaciones manuales (el buen viejo if/else), puedes simplemente añadir al campo la anotación @NotNull.

¿Cómo funciona?

Cuando Spring procesa peticiones o datos, valida automáticamente el objeto anotado con las reglas de Bean Validation. Si los datos no cumplen las reglas, Spring lanza una excepción, que podemos manejar (por ejemplo, devolver al usuario el mensaje "¡Eh, tu email es incorrecto!").

Principales anotaciones de Bean Validation API

@NotNull

Esta anotación garantiza que el valor del campo no sea null. Sin embargo, ten en cuenta: no comprueba si una cadena está vacía. Por ejemplo:

import jakarta.validation.constraints.NotNull;

public class UserDTO {
    @NotNull(message = "¡El nombre de usuario no puede estar vacío!")
    private String name;

    // Getters y setters
}

Si el campo name resulta ser null, Spring lanzará un error de validación con el mensaje "¡El nombre de usuario no puede estar vacío!".

@Size

@Size se usa para comprobar el tamaño de cadenas, colecciones, arrays y otros objetos. Por ejemplo, para asegurarte de que el nombre de usuario tenga al menos 3 caracteres y como máximo 50:

import jakarta.validation.constraints.Size;

public class UserDTO {
    @Size(min = 3, max = 50, message = "El nombre debe tener entre 3 y 50 caracteres.")
    private String username;

    // Getters y setters
}

Ten en cuenta: si solo quieres comprobar la longitud de la cadena, usa @Size. Si además necesitas comprobar que la cadena no esté en blanco, añade @NotBlank.

@Min y @Max

Estas anotaciones se usan para campos numéricos, para fijar sus valores mínimos y máximos.

Ejemplo: la edad del usuario debe estar entre 18 y 65:

import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.Max;

public class UserDTO {
    @Min(value = 18, message = "La edad no puede ser menor de 18.")
    @Max(value = 65, message = "La edad no puede ser mayor de 65.")
    private int age;

    // Getters y setters
}

@Pattern

Si te gustan las expresiones regulares, @Pattern te vendrá muy bien. Esta anotación valida cadenas según la expresión regular especificada.

Ejemplo: validación del formato de un número de teléfono

import jakarta.validation.constraints.Pattern;

public class UserDTO {
    @Pattern(regexp = "\\+\\d{1,3}-\\d{9,15}", message = "El teléfono debe tener el formato +XXX-XXXXXXXXXXXXX.")
    private String phoneNumber;

    // Getters y setters
}

Aquí \\+\\d{1,3}-\\d{9,15} significa que el teléfono debe empezar con +, seguido de entre 1 y 3 dígitos, luego un guion, y a continuación entre 9 y 15 dígitos.

@Email

No podemos olvidarnos de las direcciones de correo. La anotación @Email comprueba si la cadena introducida corresponde realmente al formato de un email:

import jakarta.validation.constraints.Email;

public class UserDTO {
    @Email(message = "Introduce un email válido.")
    private String email;

    // Getters y setters
}

@NotBlank y @NotEmpty

Estas anotaciones están pensadas para cadenas:

• @NotEmpty verifica que la cadena no sea null y que su longitud sea mayor que 0.
• @NotBlank además comprueba que la cadena no esté compuesta solo por espacios.

Ejemplo:

import jakarta.validation.constraints.NotBlank;

public class UserDTO {
    @NotBlank(message = "El nombre no puede estar vacío ni consistir solo en espacios.")
    private String name;

    // Getters y setters
}

Ejemplo: crear una clase DTO anotada

Juntémoslo todo. Imagina que tenemos un formulario de registro de usuario. El usuario debe indicar:

• Nombre (de 3 a 50 caracteres, no puede estar vacío).
• Edad (de 18 a 65).
• Email.
• Contraseña (al menos 8 caracteres).

El código podría verse así:

import jakarta.validation.constraints.*;

public class UserRegistrationDTO {

    @NotBlank(message = "El nombre no puede estar vacío.")
    @Size(min = 3, max = 50, message = "El nombre de usuario debe tener entre 3 y 50 caracteres.")
    private String username;

    @Min(value = 18, message = "La edad no puede ser menor de 18.")
    @Max(value = 65, message = "La edad no puede ser mayor de 65.")
    private int age;

    @NotBlank(message = "El email es obligatorio.")
    @Email(message = "Introduce un email correcto.")
    private String email;

    @NotBlank(message = "La contraseña es obligatoria.")
    @Size(min = 8, message = "La contraseña debe tener como mínimo 8 caracteres.")
    private String password;

    // Getters y setters
}

Ahora este objeto se puede usar para validar datos.

Ejemplo de uso en Spring MVC

No solo es útil declarar las reglas de validación, sino también verlas en acción. Imaginemos que creamos un controlador para procesar la petición POST de registro:

import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import jakarta.validation.Valid;

@RestController
@RequestMapping("/users")
@Validated
public class UserController {

    @PostMapping("/register")
    public ResponseEntity<String> registerUser(@Valid @RequestBody UserRegistrationDTO userDTO) {
        // Lógica de procesamiento del usuario (por ejemplo, guardarlo en la base de datos)
        return ResponseEntity.ok("¡Usuario registrado correctamente!");
    }
}

Aquí:

• La anotación @Valid lanza automáticamente la validación del objeto de entrada UserRegistrationDTO.
• Si los datos no cumplen las reglas, Spring devuelve automáticamente un error (normalmente código 400 y la descripción del fallo).

Errores típicos

Mucha gente comete errores al usar Bean Validation API. Aquí van algunos problemas comunes:

• Olvidar incluir Hibernate Validator en las dependencias del proyecto. Si usas Spring Boot, esto es poco probable, porque Hibernate Validator viene por defecto.
• Expresiones regulares incorrectas. Revisa tus @Pattern, si no la anotación puede rechazar todos los valores.
• Falta la anotación @Valid. Este error es especialmente frecuente en controladores — sin ella la validación simplemente no se dispara.
• Mezcla de anotaciones. Por ejemplo, usar @NotNull donde en realidad hace falta @NotBlank.

Conclusiones

La validación de datos no es solo una casilla más en la lista del desarrollador. Es protección de la integridad de los datos y de la seguridad tanto de los usuarios como de la aplicación. Bean Validation API convierte esa protección en una herramienta cómoda y poderosa, haciendo el código más limpio y fiable.

¿Quieres profundizar más? Echa un vistazo a la documentación oficial de Hibernate Validator. Allí encontrarás muchas más funcionalidades interesantes.

Y para acabar: ¡confía, pero verifica! La entrada del usuario a veces puede ser como la caja de Pandora — nunca sabes qué te puedes encontrar. Desde un despiste inocente hasta un malicioso DROP TABLE. Así que la validación no es un lujo, ¡es una necesidad!