Al cerrar la lección anterior quedó una grieta abierta: la API de CicloUrbana acepta cualquier cosa. Una estación con capacidad -5, un nombre vacío, una latitud de 200 grados o una matrícula que no se parece a RB-0142 entran sin resistencia y se guardan tan tranquilas. Las pocas comprobaciones que hemos escrito viven dispersas por los servicios, mezcladas con las reglas de negocio, y ninguna produce un mensaje útil para el cliente. En esta lección cerramos esa grieta con Jakarta Bean Validation: un mecanismo declarativo que convierte las restricciones en anotaciones sobre los propios datos, las aplica automáticamente en el borde de la aplicación y permite crear restricciones propias del dominio de Ribalta. Al terminar, ninguna petición mal formada llegará viva a la capa de servicio.

1. Por qué validar en el borde y qué capas de validación existen
2. La dependencia y el catálogo de restricciones
3. @Valid sobre @RequestBody
4. @Validated para @PathVariable y @RequestParam
5. Objetos anidados y colecciones
6. Grupos de validación: alta frente a modificación
7. Mensajes personalizados e internacionalización
8. Una restricción propia: @MatriculaBicicleta
9. Una restricción de clase: @CoordenadasValidas
10. Validación programática con Validator
11. Error de validación (400) frente a regla de negocio (409/422)
12. Errores Comunes y Consejos
13. Ejercicios

El borde es el punto por el que los datos externos entran en la aplicación: en nuestro caso, el controlador. Validar ahí falla pronto y barato —un POST con capacidad negativa se rechaza antes de tocar el servicio, el repositorio o la base de datos—, produce mensajes útiles —"la capacidad debe ser mayor que cero" en vez de un error de restricción de la base de datos— y simplifica el código de dentro: si EstacionService puede asumir que la capacidad es positiva y el nombre no está vacío, desaparece la mitad de sus if.

Ahora bien, hay varias clases de validación y confundirlas produce diseños malos:

La frontera entre "sintaxis" y "negocio" es la que más cuesta. La regla práctica: si para decidir necesitas consultar el estado del sistema, es negocio; si te basta con mirar el dato, es sintaxis. "La capacidad debe ser positiva" se decide mirando el número: sintaxis. "No puede haber dos estaciones con el mismo nombre" exige consultar el repositorio: negocio.

Bean Validation no viene con spring-boot-starter-web: hay que añadirla explícitamente.

Este starter arrastra Hibernate Validator, la implementación de referencia de Jakarta Bean Validation 3.0. Al arrancar, ValidationAutoConfiguration registra un bean LocalValidatorFactoryBean —lo verías en el informe --debug de 02-06— y a partir de ahí @Valid funciona en los controladores. Un detalle importante: las anotaciones están en jakarta.validation.constraints, no en javax.validation; Spring Boot 3 migró al espacio de nombres de Jakarta EE y buena parte de los ejemplos que hay por internet siguen usando javax, que no es compatible.

El catálogo de restricciones estándar:

Las tres primeras se confunden constantemente. Con el valor " " (tres espacios): @NotNull pasa, @NotEmpty pasa (tiene longitud 3) y @NotBlank falla; para un nombre casi siempre quieres @NotBlank. Y un apunte que ahorra sorpresas: todas las restricciones excepto @NotNull consideran válido el valor null, así que @Size(min = 3) sobre un campo nulo pasa sin protestar. Si el campo es obligatorio hay que combinarlas: @NotBlank @Size(max = 80).

Anotamos el DTO de creación de la lección anterior, renombrado ya a CrearEstacionRequest, que es el nombre definitivo que fijará 03-05:

Los marcadores {min}, {max} y {value} se sustituyen por los valores de la propia anotación, así que el mensaje no se desincroniza si mañana el límite pasa de 60 a 80 anclajes. En el controlador basta con añadir @Valid:

Si la validación falla, Spring lanza MethodArgumentNotValidException y el método del controlador no llega a ejecutarse. Con un POST de {"nombre":"","capacidad":-5,...}, la respuesta por defecto de Spring Boot 3 es:

Funciona —es un 400— pero es inservible para el cliente: no dice qué campos fallaron ni por qué. Los detalles están dentro de la excepción, y convertirlos en una respuesta con la lista de campos erróneos es el trabajo de 03-06: aquí generamos correctamente el error, allí lo presentaremos bien.

@Valid solo funciona sobre objetos. Para validar parámetros sueltos —el id de la ruta, el tamanio de la paginación— hace falta @Validated a nivel de clase, que activa un proxy AOP que intercepta las llamadas al método.

Compara este listar con el de 03-02, donde había tres líneas de Math.min y Math.max para evitar que ?tamanio=1000000 tumbara el servicio. Ahora la restricción está junto al parámetro, se documenta sola en OpenAPI (03-07) y no se puede olvidar. Dos diferencias importantes frente a @Valid:

El 500 de la tercera fila es una trampa clásica: ConstraintViolationException no está mapeada a ningún código HTTP, así que Spring la trata como un error inesperado. Es incorrecto —la culpa es del cliente, que envió ?tamanio=5000— y lo arreglaremos en el manejador global de 03-06. Recuerda la advertencia de 03-01: un 5xx por culpa del cliente contamina las alertas de producción.

Bean Validation no desciende automáticamente a los objetos anidados: hay que pedirlo con @Valid sobre el campo.

Sin ese @Valid, una petición con {"ubicacion": {"latitud": 500}} pasaría la validación sin protestar. Es uno de los fallos silenciosos más frecuentes: la validación "funciona" y sin embargo deja pasar datos imposibles.

Para las colecciones hay dos niveles, y conviene distinguirlos:

@NotEmpty y @Size se aplican a la lista —cuántos elementos tiene—, mientras que @Valid y @NotNull dentro de los corchetes angulares son restricciones sobre el tipo contenido (Bean Validation 2.0) y se aplican a cada elemento. También funciona sobre Optional<@NotBlank String> y sobre las claves y valores de un Map<@NotBlank String, @Positive Integer>.

Cuando el cuerpo entero es una lista, @Valid sobre el @RequestBody no basta: hay que envolverla en un objeto como el de arriba, o anotar el controlador con @Validated y escribir @RequestBody List<@Valid CrearBicicletaRequest> lote. La primera opción es preferible: permite añadir metadatos al lote sin romper el contrato.

Un mismo DTO puede necesitar reglas distintas según la operación: al crear una estación el nombre es obligatorio, mientras que al modificarla parcialmente puede no venir, aunque si viene debe cumplir el tamaño. Los grupos resuelven esto y son simplemente interfaces marcadoras:

Para activar un grupo hay que usar @Validated(Grupo.class), no @Valid, que no admite grupos: crear(@Validated(AlCrear.class) @RequestBody EstacionRequest peticion) y reemplazar(..., @Validated(AlActualizar.class) @RequestBody EstacionRequest peticion).

La regla del grupo Default que casi nadie recuerda: una restricción sin groups pertenece implícitamente al grupo Default, y @Validated(AlCrear.class) NO incluye Default. En el ejemplo anterior, @Size(min = 3, max = 80) no se evaluaría al crear. Se arregla declarando los dos grupos en cada anotación —@Size(..., groups = {AlCrear.class, AlActualizar.class})— o, mejor, haciendo que el grupo herede: public interface AlCrear extends jakarta.validation.groups.Default {}. Con lo segundo, @Validated(AlCrear.class) evalúa las restricciones de AlCrear y las que no tienen grupo, que es lo que casi siempre se quiere; es lo que adopta CicloUrbana.

Una advertencia de diseño: los grupos son potentes pero se vuelven ilegibles rápido. Con más de dos o tres, suele ser mejor tener DTOs separados —CrearEstacionRequest y ActualizarEstacionRequest—, cada uno con sus reglas. Es la solución que adoptará el proyecto en 03-05.

Los mensajes por defecto de Hibernate Validator vienen en inglés y son genéricos ("must not be blank"). Fijarlos en la anotación, como hemos hecho, los deja escritos en el código y en un solo idioma. La solución completa es externalizarlos en un fichero por idioma en src/main/resources:

En las anotaciones se referencia la clave entre llaves: @NotBlank(message = "{estacion.nombre.obligatorio}"). Y hay que conectar el validador con el MessageSource de Spring, porque por defecto Hibernate Validator busca sus mensajes en ValidationMessages.properties y no en el messages.properties de Spring:

Con la configuración del MessageSource en YAML:

El idioma se selecciona a partir de Accept-Language. Para que Spring MVC la respete conviene declarar el resolutor explícitamente:

Ahora un cliente que envíe Accept-Language: en recibe "The station name is required" y "Capacity must be greater than zero" sin que el código cambie una línea.

Las matrículas de la red de Ribalta tienen el formato RB-0142: dos letras fijas, un guion y cuatro dígitos. Podríamos usar @Pattern(regexp = "RB-\\d{4}") en cada sitio, pero copiar la misma expresión regular en cinco DTOs es una invitación a que un día no coincidan. Una restricción propia le pone nombre a la regla y la centraliza.

Una restricción se compone siempre de dos piezas: la anotación y el validador.

Los tres atributos message, groups y payload no son opcionales: si falta alguno, Hibernate Validator falla al arrancar con un error poco explicativo. ElementType.RECORD_COMPONENT es necesario para que la anotación se pueda colocar sobre un componente de record.

El validador:

Y su uso, tan limpio como cualquier restricción estándar:

Un detalle que conviene entender: el validador es un bean con ciclo de vida gestionado, así que puede inyectar dependencias por constructor. Eso permite validadores que consultan un repositorio... pero cuidado, eso ya sería una regla de negocio, y el apartado 11 explica por qué normalmente no debe hacerse.

Algunas reglas no se pueden expresar sobre un campo aislado porque relacionan varios. En CicloUrbana, las coordenadas deben caer dentro del término municipal de Ribalta, y eso requiere mirar latitud y longitud a la vez. La solución es una restricción a nivel de clase.

Y se anota el record completo con @CoordenadasValidas, además de las restricciones de campo que ya tenía. El bloque de buildConstraintViolationWithTemplate es lo que diferencia una restricción de clase usable de una molesta: sin él, el error de validación no tiene campo asociado y el formulario del panel de Ribalta no puede resaltar nada. Con él, el cliente recibe el error apuntando a latitud.

Nótese también que si latitud es 500 fallarán tanto @DecimalMax("90.0") como @CoordenadasValidas, y el cliente recibirá dos violaciones: Bean Validation evalúa todas las restricciones y devuelve el conjunto completo, lo cual es deseable porque un formulario debe mostrar todos sus errores de una vez.

A veces hace falta validar fuera del borde HTTP: al procesar un fichero CSV de alta masiva de bicicletas, al consumir un mensaje de una cola (módulo 7) o al validar un objeto construido dentro del propio servicio. Para eso se inyecta el Validator de Jakarta.

validator.validate(objeto) devuelve un Set<ConstraintViolation<T>> vacío si todo está bien. Cada violación expone getPropertyPath() (el campo), getMessage() (ya resuelto e internacionalizado) y getInvalidValue() (el valor rechazado).

La regla: declarativo por defecto, programático cuando necesites controlar qué pasa después del fallo. Rechazar 4.000 filas correctas porque la 137 tiene la matrícula mal sería absurdo.

Sobre getInvalidValue(), una advertencia de seguridad que se retoma en 03-06: nunca lo incluyas en la respuesta sin pensarlo. Si el campo que falló fuera una contraseña o un número de tarjeta, estarías devolviendo el dato sensible en el cuerpo del error y, casi seguro, escribiéndolo en el log.

Esta es la decisión de diseño que más discusiones genera. La política de CicloUrbana, con ejemplos:

El criterio operativo: si el cliente puede corregir la petición mirando solo lo que envió, es un 400; si necesita saber algo del estado del servidor, no lo es. capacidad: -5 se corrige solo; que la Plaza Mayor esté llena no se puede adivinar desde el cliente. Entre 409 y 422 la frontera es más difusa, y la convención del proyecto es 409 Conflict cuando el conflicto es con otro recurso existente (nombre duplicado, estación llena) y 422 Unprocessable Entity cuando la petición choca con una regla de negocio o con el estado de un recurso (bicicleta en mantenimiento, alquiler ya finalizado). Lo importante no es qué convención elijas, sino documentarla y aplicarla sin excepciones: un cliente que ve 409 en un sitio y 422 en otro para el mismo tipo de fallo no puede programar contra la API.

Hay una tentación que conviene resistir: meter reglas de negocio dentro de un ConstraintValidator. Es técnicamente posible —el validador es un bean y puede inyectar EstacionRepositorio— y hay ejemplos por internet de un @NombreEstacionUnico. Los problemas: produce el código HTTP equivocado (400 en lugar de 409); consulta la base de datos fuera de la transacción, con lo que entre la validación y el guardado otro hilo puede insertar el mismo nombre, de modo que la comprobación no es fiable; y rompe la reutilización, porque el validador solo se ejecuta si alguien llama a @Valid y el importador CSV o un consumidor de cola se lo saltarían.

La regla firme del proyecto: el validador mira el dato, el servicio mira el sistema.

Olvidar la dependencia spring-boot-starter-validation. Sin ella, las anotaciones compilan y no hacen nada. Es el fallo silencioso más frecuente: todo parece bien hasta que llega una capacidad negativa a producción. Los tres olvidos hermanos producen el mismo síntoma: @Valid en el @RequestBody (las anotaciones del DTO se ignoran), @Validated en la clase (no se evalúan las restricciones de @RequestParam y @PathVariable) y @Valid en un campo anidado (el objeto interno pasa sin validar).

Confundir @NotNull, @NotEmpty y @NotBlank. Con " ": las dos primeras pasan, la tercera falla. Para un nombre quieres @NotBlank. Relacionado: @Size no implica no nulo, porque todas las restricciones salvo @NotNull aceptan null.

Grupos sin Default. @Validated(AlCrear.class) no evalúa las restricciones sin grupo. Haz que tu grupo extienda Default.

Usar javax.validation en Spring Boot 3. Las anotaciones existen si alguna dependencia antigua arrastra el paquete, pero Hibernate Validator no las mira. El correcto es jakarta.validation.

Consejo: valida en el DTO, nunca en la entidad de dominio. La entidad puede tener reglas distintas y no debe conocer el contrato de la API: otro argumento para la separación de 03-05. Y escribe el caso inválido antes que el válido: al crear un endpoint, la primera petición del fichero .http debería llevar datos incorrectos. Si responde 200, la validación no está activa.

IniciarAlquilerRequest(Long usuarioId, Long bicicletaId) y FinalizarAlquilerRequest(Long estacionDestinoId) no tienen ninguna validación. Añádeles las restricciones adecuadas, decide qué comprobaciones no deben ser Bean Validation y justifica por qué. Aplica también validación a los parámetros del listado de alquileres, que acepta ?desde= y ?hasta= con fechas.

El ayuntamiento de Ribalta impone que la capacidad de una estación sea múltiplo de 6, porque los anclajes se instalan en bloques de seis unidades. Crea una restricción reutilizable @MultiploDe(6) con su validador, aplicable a int, Integer y long, con mensaje internacionalizado.

En la promoción "Ribalta Verano", el DTO PromocionRequest(String nombre, LocalDate inicio, LocalDate fin, Integer descuento, Boolean acumulable) debe cumplir: fin posterior a inicio; si acumulable es true, el descuento no puede superar el 20%; y la duración no puede exceder los 90 días. Impleméntalo con una restricción de clase que informe del campo correcto en cada caso.

Solución 1.

Qué NO debe ser Bean Validation:

Todas viven en AlquilerService. Bean Validation solo garantiza que los identificadores vienen y son positivos: exactamente lo que puede decidirse mirando el dato. Para el listado, con @Validated en la clase:

@DateTimeFormat no es una restricción sino una instrucción de conversión: le dice a Spring que ?desde=2026-08-01 se convierta a LocalDate. Sin ella la conversión depende del Locale y falla de forma inconsistente. Y el comentario señala lo interesante: la relación desde <= hasta no puede expresarse con Bean Validation sobre parámetros sueltos de un método. Las salidas son agrupar los parámetros en un record de filtro con una restricción de clase —como en la solución 3— o comprobarlo en el servicio, que basta para un caso aislado.

Solución 2.

Y en el DTO, junto a las restricciones que ya tenía el campo:

Con esta restricción, las cuatro estaciones existentes de Ribalta siguen siendo válidas: 24, 30, 18 y 36 son múltiplos de 6. Conviene hacer siempre esa comprobación antes de añadir una restricción a un sistema en marcha, porque una regla que invalida los datos existentes rompe el PUT de recursos que ya estaban ahí. Y sobre Number en lugar de Integer: un ConstraintValidator<MultiploDe, Integer> no se aplicaría a un campo long, mientras que Number cubre toda la familia entera; para BigDecimal haría falta otro validador, porque longValue() truncaría los decimales en silencio.

Solución 3.

Tres decisiones de diseño que conviene retener:

1. Devolver true si faltan campos obligatorios. Bean Validation no garantiza el orden de evaluación, así que la restricción de clase puede ejecutarse con campos nulos que @NotNull ya está señalando. Sin esa guarda, el cliente recibiría un NullPointerException convertido en 500, o dos mensajes contradictorios sobre el mismo campo.
2. else if entre "fin posterior" y "duración máxima". Si el fin es anterior al inicio, informar además de la duración es ruido.
3. Acumular todos los errores en lugar de salir al primero. El método sigue evaluando el descuento aunque las fechas ya hayan fallado, porque son problemas independientes y el formulario debe mostrarlos juntos. La variable valido existe para eso; un return false prematuro obligaría al usuario a dos viajes de ida y vuelta.

La grieta está cerrada. Sabes distinguir las cinco capas de validación —formato, tipo, sintaxis, consistencia y negocio— y tienes un criterio operativo para separarlas: si basta con mirar el dato es sintaxis, y si hay que consultar el estado del sistema es negocio. Conoces el catálogo completo de restricciones de Jakarta Bean Validation y las trampas clásicas: la diferencia entre @NotNull, @NotEmpty y @NotBlank, y el hecho de que todas salvo @NotNull aceptan el valor nulo sin protestar. Sabes aplicar @Valid a los cuerpos de petición y @Validated a nivel de clase para los parámetros de ruta y de consulta, y conoces la diferencia entre las excepciones que lanza cada uno —MethodArgumentNotValidException y ConstraintViolationException— y el hecho incómodo de que la segunda produce un 500 por defecto. Sabes descender a objetos anidados con @Valid en el campo, y validar cada elemento de una colección con las restricciones sobre el tipo contenido. Manejas los grupos de validación y la trampa del grupo Default, con la recomendación de no abusar de ellos.

Además, los mensajes de CicloUrbana ya están externalizados en messages.properties e internacionalizados, conectados al MessageSource de Spring y seleccionados por Accept-Language. Has construido dos restricciones propias completas: @MatriculaBicicleta con su ConstraintValidator para el formato RB-0000, y @CoordenadasValidas como restricción de clase que comprueba que una estación cae dentro del término municipal de Ribalta y asocia el error al campo correcto. Sabes validar programáticamente con el Validator inyectado cuando necesitas decidir qué hacer tras el fallo, como en la importación de lotes. Y tienes la tabla de política del proyecto sobre cuándo un fallo es 400, cuándo 409 y cuándo 422, con la regla firme de que el validador mira el dato y el servicio mira el sistema.

Queda un cabo suelto que no ha dejado de asomar. Estamos validando CrearEstacionRequest, un objeto que no es Estacion; hemos hablado de ActualizarEstacionRequest sin construirlo; y arrastramos desde 03-02 el ejercicio que demostraba por qué exponer la clase de dominio directamente no escala. El proyecto tiene ya dos representaciones de una estación conviviendo sin que hayamos ordenado esa convivencia.

La lección 03-05, DTOs y Mapeo entre Capas, la ordena. Veremos con casos concretos por qué no se exponen las entidades del dominio —acoplamiento, fugas de datos sensibles, referencias circulares, evolución imposible del contrato—, diseñaremos la jerarquía completa de DTOs de CicloUrbana separando los de petición de los de respuesta, y compararemos las estrategias de mapeo: manual, MapStruct con su configuración Maven y su código generado, y ModelMapper con sus riesgos. Decidiremos dónde vive el mapeo y construiremos EstacionResponse, EstacionDetalleResponse con su lista de BicicletaResumen, y AlquilerResponse. Al terminar, el dominio de Ribalta y su contrato público serán por fin dos cosas separadas.