3. El modelo de la acción
Una acción necesita la información enviada por el navegador: los parámetros de la URL ([?name=martin&age=42]), los campos de un formulario, el cuerpo JSON de la solicitud y, a veces, un encabezado HTTP de la solicitud. El curso original denomina al conjunto de esta información el modelo de la acción. Este capítulo muestra cómo [Spring MVC] proporciona esta información a la acción, la convierte al tipo correcto y la valida. Este proceso se llama enlace de datos ([data binding]).
Nota sobre la terminología: en [Spring MVC], la palabra “modelo” ([Model]) designa principalmente los datos que una acción pasa a su vista (capítulo 4, “La vista y su modelo”). El modelo de una acción, tal como se usa en este capítulo, es lo que ella recibe.
Los ejemplos 07 a 12 son, como los del capítulo anterior, módulos [Maven] de la carpeta [examples]. Puede ejecutar uno de ellos abriendo una terminal en esa carpeta y escribiendo [../mvnw spring-boot:run] ([..\mvnw spring-boot:run] en [Windows]); [Ctrl-C] detiene el servidor. Cada ejemplo tiene un archivo llamado [application.properties] que tiene este aspecto:
| # el puerto de escucha del servidor (8080 por defecto)
server.port=5000
# las respuestas de error de Spring Boot no contienen la pila de llamadas
spring.web.error.include-stacktrace=never
|
- línea 2: el puerto de escucha del servidor;
- línea 4: cuando una solicitud falla, [Spring Boot] responde con un documento JSON de error (veremos muchos de ellos en este capítulo). Esta propiedad evita que se incluya la pila de llamadas de la excepción ([stack trace]), que es larga y nunca debe mostrarse a un usuario. Esto es necesario porque la dependencia [spring-boot-devtools] (las herramientas de desarrollo, declarada en el [pom.xml] padre) modifica varios valores predeterminados durante el desarrollo: en particular, agrega a este JSON el mensaje de la excepción (propiedad [spring.web.error.include-message]) y la pila de llamadas ([spring.web.error.include-stacktrace]). Conservamos el mensaje, porque es útil para entender lo que ocurrió; en producción, sin las herramientas de desarrollo, también desaparece.
3.1. Ejemplo 07: los parámetros de la URL
El archivo [controllers/ParametersController.java]:
| package example07.controllers;
import java.util.Map;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/parameters")
public class ParametersController {
// /parameters/action01?name=martin: el parámetro de URL [name] -> el parámetro de acción [name]
// required = false: el parámetro puede faltar, entonces vale null
@GetMapping("/action01")
public String action01(@RequestParam(required = false) String name) {
return "name = [%s], of type %s".formatted(name, name == null ? "null" : name.getClass().getSimpleName());
}
// /parameters/action02?age=42: el valor se CONVIERTE al tipo del parámetro;
// sin required = false, el parámetro es obligatorio
@GetMapping("/action02")
public String action02(@RequestParam int age) {
return "age = [%d], of type int".formatted(age);
}
// /parameters/action03?age=42: Integer (y no int) acepta el valor null
@GetMapping("/action03")
public String action03(@RequestParam(required = false) Integer age) {
return "age = [%s]".formatted(age);
}
// /parameters/action04?page=2: un valor por defecto si falta el parámetro
@GetMapping("/action04")
public String action04(@RequestParam(defaultValue = "1") int page) {
return "page = [%d]".formatted(page);
}
// /parameters/action05?q=spring: el nombre del parámetro de URL, cuando difiere
@GetMapping("/action05")
public String action05(@RequestParam(name = "q", required = false) String search) {
return "search = [%s]".formatted(search);
}
// /parameters/action06?name=martin&age=42: todos los parámetros a la vez
@GetMapping("/action06")
public Map<String, String> action06(@RequestParam Map<String, String> parameters) {
return parameters;
}
}
|
Comentemos este código:
- Líneas 16-17: la anotación [@RequestParam] asocia un parámetro de la acción con un parámetro de la URL (la parte que sigue a [?], conocida como cadena de consulta o [query string]). Salvo que se indique otra cosa, el parámetro de la URL tiene el mismo nombre que el parámetro de [Java]: [name]. Este nombre solo se conoce en tiempo de ejecución porque el proyecto padre de [Spring Boot] indica al compilador que lo conserve en el código compilado (opción [-parameters]). Una anotación puede aceptar argumentos con nombre, llamados atributos: [required = false] indica que el parámetro puede omitirse; en ese caso, equivale a [null]. Línea 18: el método [formatted] reemplaza cada aparición de [%s] en la cadena por el argumento siguiente; [name.getClass().getSimpleName()] es el nombre corto del tipo del valor;
- Líneas 23-24: el parámetro se declara con el tipo [int]: [Spring MVC] convierte la cadena recibida (["42"]) en un número. Sin el atributo [required = false], [@RequestParam] hace que el parámetro sea obligatorio: este es el valor predeterminado de [required]. Un parámetro ausente, o cuya conversión falla, provoca un error 400, y la acción no se ejecuta;
- líneas 29-30: un [int] no puede ser igual a [null]. Para un número opcional, el parámetro se declara con el tipo [Integer], la clase [Java], que "envuelve" un [int] ([wrapper]): un objeto [Integer] puede tener el valor [null], lo que permite distinguir entre "sin edad" y "edad 0";
- líneas 35-36: el atributo [defaultValue] proporciona el valor que se usa cuando falta el parámetro (también hace que el parámetro sea opcional). Es una cadena, que se convierte de la misma manera que se convertiría el valor recibido;
- líneas 41-42: el atributo [name] especifica el nombre del parámetro de la URL cuando difiere del del parámetro [Java]: el parámetro [search] de la acción recibe el parámetro [q] de la URL;
- Líneas 47-48: un parámetro de tipo [Map<String, String>] anotado con [@RequestParam] recibe todos los parámetros de la URL, sin conversión: un diccionario (nombre del parámetro, valor). La acción lo devuelve tal cual, y [Spring MVC] lo serializa a JSON.
Los resultados:
| curl -i "http://localhost:5000/parameters/action01?name=martin"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 31
name = [martin], of type String
|
| curl -i "http://localhost:5000/parameters/action01"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 27
name = [null], of type null
|
El servidor [Tomcat] no muestra el texto [OK] después del código 200 en la primera línea: este texto es opcional en HTTP/1.1; solo importa el código. Las comillas alrededor de la URL son obligatorias cuando esta contiene el carácter [&], que tiene un significado especial para la consola; las incluimos en todos los casos. Un parámetro de tipo [int]:
| curl -i "http://localhost:5000/parameters/action02?age=42"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 23
age = [42], of type int
|
| curl -i "http://localhost:5000/parameters/action02?age=abc"
|
| HTTP/1.1 400
Content-Type: application/json
{"timestamp":"2026-09-25T16:46:05.177Z","status":400,"error":"Bad Request","message":"Method parameter 'age': Failed to convert value of type 'java.lang.String' to required type 'int'; For input string: \"abc\"","path":"/parameters/action02"}
|
| curl -i "http://localhost:5000/parameters/action02"
|
| HTTP/1.1 400
Content-Type: application/json
{"timestamp":"2026-09-25T16:46:05.205Z","status":400,"error":"Bad Request","message":"Required parameter 'age' is not present.","path":"/parameters/action02"}
|
Esta es una diferencia significativa con [ASP.NET Core MVC], donde una conversión imposible no impedía que la acción se ejecutara. Con [@RequestParam], [Spring MVC] lanza una excepción antes de llamar a la acción: [MethodArgumentTypeMismatchException] para una conversión imposible, [MissingServletRequestParameterException] para un parámetro obligatorio ausente (la consola del servidor muestra los nombres de estas excepciones). Un componente de [Spring MVC] las convierte en una respuesta de error 400 ([Bad Request], solicitud no válida), y [Spring Boot] genera el cuerpo de esta respuesta: es la respuesta de error JSON que ya vimos en el capítulo anterior. Sus campos:
- [timestamp]: la fecha y hora del error (en Tiempo Universal Coordinado);
- [status], [error]: el código HTTP y su descripción;
- [message]: el mensaje de la excepción, incluido aquí porque las herramientas de desarrollo lo solicitaron;
- [path]: la ruta de la solicitud.
Un navegador que solicita una página con el código HTML recibe en su lugar una página de error mínima: la "Whitelabel Error Page". En el ejemplo 12 veremos cómo manejar usted mismo estas excepciones. Con el tipo [Integer]:
| curl -i "http://localhost:5000/parameters/action03?age=42"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 10
age = [42]
|
| curl -i "http://localhost:5000/parameters/action03"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 12
age = [null]
|
| curl -i "http://localhost:5000/parameters/action03?age=abc"
|
| HTTP/1.1 400
Content-Type: application/json
{"timestamp":"2026-09-25T16:46:05.250Z","status":400,"error":"Bad Request","message":"Method parameter 'age': Failed to convert value of type 'java.lang.String' to required type 'java.lang.Integer'; For input string: \"abc\"","path":"/parameters/action03"}
|
Un parámetro ausente se trata como [null]; un parámetro no válido siempre produce un error 400. El valor predeterminado:
| curl -i "http://localhost:5000/parameters/action04"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 10
page = [1]
|
| curl -i "http://localhost:5000/parameters/action04?page=2"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 10
page = [2]
|
| curl -i "http://localhost:5000/parameters/action04?page="
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 10
page = [1]
|
Un parámetro presente pero vacío ([?page=]) se trata como si faltara: toma el valor predeterminado. Las dos últimas acciones:
| curl -i "http://localhost:5000/parameters/action05?q=spring"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 17
search = [spring]
|
| curl -i "http://localhost:5000/parameters/action06?name=martin&age=42"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 28
{"name":"martin","age":"42"}
|
Aquí, age es una cadena (["42"]): al no haber un tipo declarado, no hay conversión. Por último, los nombres de los parámetros distinguen mayúsculas de minúsculas:
| curl -i "http://localhost:5000/parameters/action01?NAME=martin"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 27
name = [null], of type null
|
El parámetro [NAME] no es el mismo que el parámetro [name], que por lo tanto está ausente. Esta es otra diferencia con [ASP.NET Core MVC], que ignora la distinción entre mayúsculas y minúsculas. Observe que:
- [@RequestParam] vincula un parámetro de la acción con un parámetro del mismo nombre en la URL, incluidas las mayúsculas (atributo [name] si los nombres difieren);
- el parámetro es obligatorio de manera predeterminada; [required = false] lo hace opcional, y [defaultValue] proporciona un valor de respaldo;
- su valor se convierte al tipo declarado, y una conversión imposible produce un error 400 sin ejecutar la acción. Un tipo de objeto ([Integer], no [int]) permite recibir [null].
Los caracteres acentuados y los espacios se codifican en una URL ([%C3%A9] para [é], etc.): [Spring MVC] los decodifica antes del enlace. El navegador muestra la URL codificada y el JSON recibido:

Cuando una acción tiene varios parámetros, estos se describen mediante una clase. Cada campo de la clase tiene restricciones de validación, en forma de anotaciones. Estas están definidas por [Bean Validation], el estándar de validación de [Java] (paquete [jakarta.validation]), cuya implementación más utilizada es [Hibernate Validator]. No forman parte de [Spring MVC]: es necesario agregar el starter de validación al [pom.xml] del ejemplo:
| <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>course.springmvc</groupId>
<artifactId>examples</artifactId>
<version>1.0</version>
</parent>
<artifactId>example08</artifactId>
<dependencies>
<!-- validación (Bean Validation, Hibernate Validator) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
</dependencies>
</project>
|
- líneas 6-10: el proyecto padre, [pom.xml], en la carpeta [examples];
- Líneas 13-19: el starter [spring-boot-starter-validation] incluye [Hibernate Validator] y lo configura. Recuerde que un starter es una dependencia que agrupa otras dependencias, junto con sus versiones y su configuración automática. Los ejemplos 09 a 12 comparten la misma dependencia.
El archivo [models/PersonModel.java]:
| package example08.models;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Pattern;
import jakarta.validation.constraints.Size;
// el modelo de la acción: una clase cuyos campos llevan todos sus restricciones
public class PersonModel {
@NotBlank(message = "the name is required")
@Size(min = 2, max = 20, message = "the name must have 2 to 20 characters")
private String name;
@NotNull(message = "the age is required")
@Min(value = 0, message = "the age must be between 0 and 150")
@Max(value = 150, message = "the age must be between 0 and 150")
private Integer age;
@NotNull(message = "the title is required")
@Pattern(regexp = "Mr|Mme|Melle", message = "unknown title")
private String title;
// opcional: sin @NotNull
@Email(message = "invalid email address")
private String email;
// los accesores (getters y setters): el enlace del modelo llena
// cada campo mediante su setter; la serialización JSON lo lee mediante su getter
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public Integer getAge() { return age; }
public void setAge(Integer age) { this.age = age; }
public String getTitle() { return title; }
public void setTitle(String title) { this.title = title; }
public String getEmail() { return email; }
public void setEmail(String email) { this.email = email; }
}
|
Comentemos este código:
- líneas 3-9: las anotaciones de validación, todas en el paquete [jakarta.validation.constraints];
- líneas 14-16: el nombre es obligatorio y no puede estar vacío ([@NotBlank] rechaza [null], una cadena vacía y una cadena formada por espacios) y debe tener entre 2 y 20 caracteres ([@Size]). Cada anotación acepta un mensaje de error personalizado (atributo [message]);
- líneas 18-21: la edad se convierte en un entero, es obligatoria ([@NotNull]) y debe estar entre 0 y 150 ([@Min], [@Max]). Se declara como [Integer] en lugar de [int], de modo que la "ausencia de edad" ([null]) sea detectada por [@NotNull] en lugar de asignarse como 0;
- líneas 23-25: el título debe coincidir con la expresión regular [Mr|Mme|Melle] ([@Pattern]): debe ser uno de estos tres valores;
- líneas 28-29: la dirección de correo electrónico es opcional (sin [@NotNull]); si está presente, debe ser válida ([@Email]). Todas las restricciones distintas de [@NotNull] y [@NotBlank] aceptan el valor [null]: eso es lo que hace opcional a un campo;
- líneas 33-43: los accesores. Por convención, el valor del campo [name] se lee mediante el método [getName] ([getter]) y se escribe mediante el método [setName] ([setter]). Una clase que tiene un constructor sin parámetros (en este caso, el que proporciona implícitamente [Java]) y accesores que siguen esta convención se denomina JavaBean. Esta es la forma que espera el enlace de datos: [Spring MVC] crea el objeto mediante su constructor sin parámetros y luego, para cada parámetro de la solicitud, llama al setter del mismo nombre: [setName("martin")] para [?name=martin], después de convertir el valor al tipo del setter. El convertidor JSON, en cambio, lee los campos mediante sus getters.
El archivo [controllers/PersonsController.java]:
| package example08.controllers;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import example08.models.PersonModel;
import jakarta.validation.Valid;
@RestController
@RequestMapping("/persons")
public class PersonsController {
// /persons/action01?name=martin&age=42&title=Mr
// @Valid: el modelo se valida ANTES de que se ejecute la acción; si es
// inválido, la solicitud se rechaza AUTOMÁTICAMENTE (error 400)
@GetMapping("/action01")
public Map<String, Object> action01(@Valid PersonModel person) {
Map<String, Object> response = new LinkedHashMap<>();
response.put("person", person);
response.put("ageType", person.getAge().getClass().getSimpleName());
return response;
}
}
|
- Línea 21: la acción recibe un [PersonModel]. El parámetro no tiene la anotación [@RequestParam]: para un parámetro cuyo tipo no es un tipo "simple" (cadena, número, fecha, etc.), [Spring MVC] supone la anotación [@ModelAttribute], que podría haberse escrito. El parámetro es entonces un objeto de comando ([command object]), creado y poblado por el enlace de datos como se acaba de describir. Los parámetros de consulta que no corresponden a ningún setter se ignoran;
- línea 21: la anotación [@Valid] (de [jakarta.validation]) solicita que el objeto se valide después de haber sido poblado, comprobando las restricciones de sus campos. Si el enlace de datos o la validación fallan, [Spring MVC] lanza la excepción [MethodArgumentNotValidException]: la acción no se ejecuta y la respuesta es un error 400. Esto equivale al atributo [[ApiController]] de [ASP.NET Core MVC];
- líneas 22-25: la acción devuelve la persona recibida y el tipo de su edad. [LinkedHashMap] es un diccionario que conserva el orden de inserción de sus claves: JSON las mostrará en ese orden.
El archivo [application.properties] del ejemplo tiene dos líneas adicionales:
| # el puerto de escucha del servidor (8080 por defecto)
server.port=5000
# las respuestas de error de Spring Boot no contienen la pila de llamadas
spring.web.error.include-stacktrace=never
# las respuestas de error detallan los errores de validación
spring.web.error.include-binding-errors=always
|
- Línea 6: cuando la respuesta de error proviene de una comprobación de validación, contiene la lista de errores (campo [errors]). Las herramientas de desarrollo ya lo habilitan; esta línea lo mantiene habilitado en producción. Sin ella, y sin las herramientas de desarrollo, la respuesta de error se reduce a [{"timestamp":"...","status":400,"error":"Bad Request","path":"/persons/action01"}]: el cliente sabe que su solicitud es incorrecta, pero no por qué.
Una solicitud válida, con un parámetro [pirate] que no corresponde a ningún campo:
| curl -i "http://localhost:5000/persons/action01?name=martin&age=42&title=Mr&pirate=1"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 83
{"person":{"age":42,"email":null,"name":"martin","title":"Mr"},"ageType":"Integer"}
|
La edad es efectivamente un número (un [Integer]), y el parámetro [pirate] fue ignorado. Las propiedades de la persona están ordenadas alfabéticamente: este es el comportamiento predeterminado de [Jackson] 3, la biblioteca JSON que utiliza [Spring MVC]. Una consulta no válida (el JSON de la respuesta se ha formateado para facilitar la lectura: una propiedad por línea):
| curl -i "http://localhost:5000/persons/action01?name=m&age=abc&title=Dr&email=xx"
|
| HTTP/1.1 400
Content-Type: application/json
{
"timestamp": "2026-09-25T16:46:41.520Z",
"status": 400,
"error": "Bad Request",
"message": "Validation failed for object='personModel'. Error count: 4",
"errors": [
{
"arguments": [{"arguments":null,"code":"age","codes":["personModel.age","age"],"defaultMessage":"age"}],
"bindingFailure": true,
"code": "typeMismatch",
"codes": ["typeMismatch.personModel.age","typeMismatch.age","typeMismatch.java.lang.Integer","typeMismatch"],
"defaultMessage": "Failed to convert property value of type 'java.lang.String' to required type 'java.lang.Integer' for property 'age'; For input string: \"abc\"",
"field": "age",
"objectName": "personModel",
"rejectedValue": "abc"
},
{
"objectName": "personModel",
"field": "email",
"rejectedValue": "xx",
"codes": ["Email.personModel.email","Email.email","Email.java.lang.String","Email"],
"arguments": [{"arguments":null,"code":"email","codes":["personModel.email","email"],"defaultMessage":"email"},[],{"arguments":null,"codes":[".*"],"defaultMessage":".*"}],
"bindingFailure": false,
"code": "Email",
"defaultMessage": "invalid email address"
},
{
"objectName": "personModel",
"field": "title",
"rejectedValue": "Dr",
"codes": ["Pattern.personModel.title","Pattern.title","Pattern.java.lang.String","Pattern"],
"arguments": [{"arguments":null,"code":"title","codes":["personModel.title","title"],"defaultMessage":"title"},[],{"arguments":null,"codes":["Mr|Mme|Melle"],"defaultMessage":"Mr|Mme|Melle"}],
"bindingFailure": false,
"code": "Pattern",
"defaultMessage": "unknown title"
},
{
"objectName": "personModel",
"field": "name",
"rejectedValue": "m",
"codes": ["Size.personModel.name","Size.name","Size.java.lang.String","Size"],
"arguments": [{"arguments":null,"code":"name","codes":["personModel.name","name"],"defaultMessage":"name"},20,2],
"bindingFailure": false,
"code": "Size",
"defaultMessage": "the name must have 2 to 20 characters"
}
],
"path": "/persons/action01"
}
|
La acción no se ejecutó. El campo [errors] enumera los errores, uno por cada campo rechazado. Para cada uno:
- [field], [rejectedValue]: el campo y el valor rechazado;
- [defaultMessage]: el mensaje de error; es el más útil;
- [code]: el nombre de la restricción violada ([Size], [Email]...) o [typeMismatch] para un error de conversión; [bindingFailure] equivale a [true] para un error de conversión (el error se produjo durante el enlace, antes de la validación);
- [codes], [arguments]: claves y valores utilizados para buscar el mensaje en un archivo de mensajes. Así es como el mensaje de error en inglés del error de conversión (clave [typeMismatch...]) se reemplazará por un mensaje personalizado, como se muestra en el ejemplo 19.
El orden de los errores no está garantizado: puede cambiar de una ejecución a otra. Lo mismo ocurre sin ningún parámetro:
| curl -i http://localhost:5000/persons/action01
|
| HTTP/1.1 400
Content-Type: application/json
{
"timestamp": "2026-09-25T16:46:41.574Z",
"status": 400,
"error": "Bad Request",
"message": "Validation failed for object='personModel'. Error count: 3",
"errors": [
{
"objectName": "personModel",
"field": "age",
"rejectedValue": null,
"codes": ["NotNull.personModel.age","NotNull.age","NotNull.java.lang.Integer","NotNull"],
"arguments": [{"arguments":null,"code":"age","codes":["personModel.age","age"],"defaultMessage":"age"}],
"bindingFailure": false,
"code": "NotNull",
"defaultMessage": "the age is required"
},
{
"objectName": "personModel",
"field": "title",
"rejectedValue": null,
"codes": ["NotNull.personModel.title","NotNull.title","NotNull.java.lang.String","NotNull"],
"arguments": [{"arguments":null,"code":"title","codes":["personModel.title","title"],"defaultMessage":"title"}],
"bindingFailure": false,
"code": "NotNull",
"defaultMessage": "the title is required"
},
{
"objectName": "personModel",
"field": "name",
"rejectedValue": null,
"codes": ["NotBlank.personModel.name","NotBlank.name","NotBlank.java.lang.String","NotBlank"],
"arguments": [{"arguments":null,"code":"name","codes":["personModel.name","name"],"defaultMessage":"name"}],
"bindingFailure": false,
"code": "NotBlank",
"defaultMessage": "the name is required"
}
],
"path": "/persons/action01"
}
|
Un solo mensaje por campo: las restricciones [@Size] y [@Pattern] aceptan el valor [null]; solo [@NotBlank] y [@NotNull] lo rechazan. Al igual que [@RequestParam], el enlace de datos distingue mayúsculas de minúsculas: con [?NAME=martin&age=42&title=Mr], se obtiene el error "el nombre es obligatorio", porque [NAME] no coincide con ningún setter.
3.2.1. ¿Por qué una clase JavaBean y no un record?
A partir de [Java] 16, un record de una sola línea describe una clase de datos no modificable: [record Point(int x, int y) {}] declara los campos [x] y [y], un constructor que los recibe todos, y los métodos de lectura [x()] y [y()]. Un record no tiene setters. [Spring MVC] sabe poblar un record: llama a su constructor con los parámetros de consulta (esto se denomina enlace por constructor). Reemplacemos, solo para ver, la clase [PersonModel] por el record equivalente (la acción lee entonces la edad mediante [person.age()]):
| public record PersonModel(
@NotBlank(message = "the name is required")
@Size(min = 2, max = 20, message = "the name must have 2 to 20 characters")
String name,
@NotNull(message = "the age is required")
@Min(value = 0, message = "the age must be between 0 and 150")
@Max(value = 150, message = "the age must be between 0 and 150")
Integer age,
@NotNull(message = "the title is required")
@Pattern(regexp = "Mr|Mme|Melle", message = "unknown title")
String title,
@Email(message = "invalid email address")
String email) {
}
|
Una consulta válida devuelve el mismo resultado, salvo por el orden de las propiedades JSON: las propiedades de un record se escriben en el orden de sus componentes ([{"name":"martin","age":42,"title":"Mr","email":null}]). Pero la consulta no válida anterior ahora devuelve un único error:
| curl -i "http://localhost:5000/persons/action01?name=m&age=abc&title=Dr&email=xx"
|
| HTTP/1.1 400
Content-Type: application/json
{
"timestamp": "2026-09-25T16:47:45.491Z",
"status": 400,
"error": "Bad Request",
"message": "Validation failed for object='personModel'. Error count: 1",
"errors": [
{
"arguments": [{"arguments":null,"code":"age","codes":["personModel.age","age"],"defaultMessage":"age"}],
"bindingFailure": true,
"code": "typeMismatch",
"codes": ["typeMismatch.personModel.age","typeMismatch.age","typeMismatch.java.lang.Integer","typeMismatch"],
"defaultMessage": "Failed to convert value of type 'java.lang.String' to required type 'java.lang.Integer'; For input string: \"abc\"",
"field": "age",
"objectName": "personModel",
"rejectedValue": "abc"
}
],
"path": "/persons/action01"
}
|
La conversión de la edad falló; por lo tanto, no se pudo llamar al constructor del record porque a uno de sus parámetros le faltaba un valor; sin objeto, no hay validación: los errores en el nombre, el título y la dirección de correo no se informan. Con un JavaBean, en cambio, cada setter se llama de forma independiente: un campo mal convertido se deja vacío y recibe un error de conversión, mientras que los demás se rellenan, y la validación continúa (ejemplo 09). Para un formulario HTML, donde el objetivo es informar de todos los errores a la vez, esto es esencial: por eso todos los formularios de este curso son formularios JavaBean. Un record sigue siendo válido para un modelo cuyos campos no pueden tener errores de conversión: es el caso del ejemplo 10.
Este rechazo automático es adecuado para un servidor JSON, consultado por un cliente [JavaScript] que muestra los errores a su manera. Para una aplicación HTML, un error JSON no tiene sentido: el objetivo es volver a mostrar el formulario con sus errores. El ejemplo siguiente muestra cómo conservar el control.
3.3. Ejemplo 09: validación realizada por la acción
La clase [PersonModel] del ejemplo 09 es idéntica a la del ejemplo 08; solo cambia el controlador. El archivo [controllers/PersonsController.java]:
| package example09.controllers;
import java.util.stream.Collectors;
import org.springframework.http.MediaType;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import example09.models.PersonModel;
import jakarta.validation.Valid;
@RestController
@RequestMapping("/persons")
public class PersonsController {
// un parámetro BindingResult, justo después del modelo: la acción se ejecuta
// SIEMPRE, y es la acción la que decide qué hacer con un modelo inválido
@GetMapping(value = "/action01", produces = MediaType.TEXT_HTML_VALUE)
public String action01(@Valid PersonModel person, BindingResult result) {
// result: el resultado del enlace Y de la validación del modelo
if (!result.hasErrors()) {
return "<p>Welcome %s %s (%d years old)</p>".formatted(person.getTitle(), person.getName(), person.getAge());
}
// los errores, campo por campo
String items = result.getFieldErrors().stream()
.map(error -> "<li>%s: %s</li>".formatted(error.getField(), error.getDefaultMessage()))
.collect(Collectors.joining());
return "<p>The form contains errors:</p><ul>" + items + "</ul>";
}
}
|
Analicemos este código:
- Línea 20: el atributo [produces] de [@GetMapping] establece el tipo de la respuesta: [MediaType.TEXT_HTML_VALUE] es la constante ["text/html"]. Por lo tanto, la cadena devuelta por la acción se envía como una página HTML;
- línea 21: la acción tiene un segundo parámetro, de tipo [BindingResult], colocado inmediatamente después de el modelo validado. Su presencia lo cambia todo: ante un error de enlace o de validación, [Spring MVC] ya no lanza una excepción; almacena los errores en este [BindingResult] y ejecuta la acción, que decide qué hacer con ellos. [BindingResult] cumple la misma función que [ModelState] en [ASP.NET Core MVC];
- líneas 23-25: [hasErrors()] indica si hay errores. Si no los hay, se devuelve una página de bienvenida ([%d] se reemplaza por un entero);
- líneas 27-29: de lo contrario, la lista de errores. [getFieldErrors()] devuelve la lista de errores asociados a un campo ([FieldError]), junto con el nombre del campo ([getField()]) y el mensaje ([getDefaultMessage()]). El procesamiento utiliza la API de [Java] streams ([Stream]): [stream()] genera los elementos de la lista uno por uno, [map] transforma cada uno (en este caso, un error en una línea: HTML [<li>]), [collect(Collectors.joining())] concatena todo en una cadena. El argumento de [map] es una lambda: una función anónima, escrita como [parameter -> expression];
- línea 30: una página que enumera los errores. En ambos casos, la respuesta tiene un código de estado 200.
Una solicitud válida en un navegador:

Una solicitud no válida:

Un error de conversión aparece en [BindingResult] como un error de validación, pero no impide que se validen los demás campos:
| curl -i "http://localhost:5000/persons/action01?name=m&age=abc&title=Mr"
|
| HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
Content-Length: 247
<p>The form contains errors:</p><ul><li>age: Failed to convert property value of type 'java.lang.String' to required type 'java.lang.Integer' for property 'age'; For input string: "abc"</li><li>name: the name must have 2 to 20 characters</li></ul>
|
Esta es la técnica que utilizarán todos los formularios del caso de estudio (véase el ejemplo 19): la acción recibe el formulario (un JavaBean anotado con [@Valid]) seguido de un [BindingResult], y vuelve a mostrar el formulario si hay errores.
3.4. Ejemplo 10: parámetros múltiples
Un mismo parámetro puede aparecer varias veces en una solicitud: es el caso de las casillas de verificación de un formulario o de una lista de selección múltiple ([?color=red&color=green]).
El archivo [controllers/ArraysController.java]:
| package example10.controllers;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import org.springframework.validation.BindingResult;
import org.springframework.validation.ObjectError;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import example10.models.ChoiceModel;
import jakarta.validation.Valid;
@RestController
@RequestMapping("/arrays")
public class ArraysController {
// /arrays/action01?color=red&color=green: un parámetro simple
@GetMapping("/action01")
public Map<String, String> action01(@RequestParam(required = false) String color) {
Map<String, String> response = new LinkedHashMap<>();
response.put("color", color);
return response;
}
// /arrays/action02?color=red&color=green: una lista
@GetMapping("/action02")
public Map<String, Object> action02(@RequestParam(required = false) List<String> color) {
List<String> colors = color == null ? List.of() : color;
Map<String, Object> response = new LinkedHashMap<>();
response.put("color", colors);
response.put("count", colors.size());
return response;
}
// /arrays/action03?color=red: una lista, validada por ChoiceModel
@GetMapping("/action03")
public Map<String, Object> action03(@Valid ChoiceModel choice, BindingResult result) {
Map<String, Object> response = new LinkedHashMap<>();
response.put("colors", choice.color());
response.put("valid", !result.hasErrors());
response.put("errors", result.getAllErrors().stream().map(ObjectError::getDefaultMessage).toList());
return response;
}
}
|
La acción [action01] (líneas 22-27) muestra lo que recibe un parámetro simple:
| curl -i "http://localhost:5000/arrays/action01?color=red"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 15
{"color":"red"}
|
| curl -i "http://localhost:5000/arrays/action01?color=red&color=green"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 21
{"color":"red,green"}
|
Un parámetro de tipo [String] que recibe varios valores los concatena, separados por comas: ["red,green"]. Esto es una trampa: se cree que se recibe un solo color, pero en realidad se recibe una lista de colores disfrazada. Un parámetro de tipo lista ([action02], líneas 30-37) los recibe todos, cada uno en un elemento distinto de la lista. [List<String>] es una lista de cadenas; [List.of()] (línea 32) es una lista vacía, que reemplaza a [null] cuando falta el parámetro:
| curl -i "http://localhost:5000/arrays/action02?color=red"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 27
{"color":["red"],"count":1}
|
| curl -i "http://localhost:5000/arrays/action02?color=red&color=green"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 35
{"color":["red","green"],"count":2}
|
| curl -i "http://localhost:5000/arrays/action02"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 22
{"color":[],"count":0}
|
A la inversa, un solo valor que contiene comas se divide:
| curl -i "http://localhost:5000/arrays/action02?color=red,green"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 35
{"color":["red","green"],"count":2}
|
La conversión de una cadena en una lista, al igual que la de una lista en una cadena, utiliza la coma como separador. También podríamos haber declarado un arreglo ([String[] color]). Solo queda validar la lista. El archivo [models/ChoiceModel.java]:
| package example10.models;
import java.util.List;
import jakarta.validation.constraints.Pattern;
import jakarta.validation.constraints.Size;
// una lista y una restricción sobre CADA elemento de la lista:
// la anotación @Pattern se coloca DENTRO del tipo genérico List<...>
public record ChoiceModel(
@Size(min = 1, message = "choose at least one color")
List<@Pattern(regexp = "red|green|blue", message = "unknown color: ${validatedValue}") String> color) {
// el constructor "compacto" de un record: una lista ausente se convierte en una lista vacía
public ChoiceModel {
color = color == null ? List.of() : color;
}
}
|
Comentemos este código:
- línea 10: [ChoiceModel] es un record de un solo campo (véanse los ejemplos 03 y 08), [color]. El enlace por constructor no plantea ningún problema aquí: una lista de cadenas no puede producir un error de conversión;
- línea 12: [@Size(min = 1)], cuando se aplica a una lista, se refiere al número de elementos de la lista: debe haber al menos uno;
- línea 13: la anotación [@Pattern] se coloca dentro del tipo genérico, antes de [String]: no se aplica a la lista, sino a cada uno de sus elementos. Cada color debe ser [red], [green], or [blue]. En el mensaje, [${validatedValue}] se reemplaza por el valor rechazado;
- líneas 16-18: el constructor compacto de un record: un bloque que se ejecuta al comienzo del constructor, antes de que se asignen los campos, y que puede modificar sus parámetros. Aquí, una lista ausente ([null]) se convierte en una lista vacía.
La acción [action03] del controlador [ArraysController] recibe un [ChoiceModel] validado, seguido de un [BindingResult], y devuelve su contenido junto con el estado de la validación. [choice.color()] lee el campo del record. [result.getAllErrors()] devuelve todos los errores, y [ObjectError::getDefaultMessage] es una referencia a método: una notación abreviada de la lambda [error -> error.getDefaultMessage()]. [toList()] recopila el stream en una lista.
| curl -i "http://localhost:5000/arrays/action03?color=red&color=green"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 51
{"colors":["red","green"],"valid":true,"errors":[]}
|
| curl -i "http://localhost:5000/arrays/action03?color=red&color=black"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 74
{"colors":["red","black"],"valid":false,"errors":["unknown color: black"]}
|
| curl -i "http://localhost:5000/arrays/action03"
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 66
{"colors":[],"valid":false,"errors":["choose at least one color"]}
|
[ASP.NET Core MVC] requería un método de validación escrito en [C#] para verificar cada elemento de la lista; con [Bean Validation], basta una anotación en el tipo genérico.
3.5. Ejemplo 11: los parámetros de una solicitud POST
Un formulario HTML enviado mediante el método POST coloca sus campos en el cuerpo de la solicitud, no en la URL. El archivo [controllers/PostController.java]:
| package example11.controllers;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.util.MultiValueMap;
import org.springframework.validation.BindingResult;
import org.springframework.validation.ObjectError;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import example11.models.PersonModel;
import jakarta.validation.Valid;
import tools.jackson.databind.JsonNode;
@RestController
@RequestMapping("/post")
public class PostController {
// los campos de un formulario HTML (cuerpo application/x-www-form-urlencoded)
@PostMapping("/action01")
public Map<String, Object> action01(@RequestHeader("Content-Type") String type,
@RequestParam MultiValueMap<String, String> fields) {
Map<String, Object> response = new LinkedHashMap<>();
response.put("receivedType", type);
response.put("fields", fields);
return response;
}
// un cuerpo JSON: @RequestBody lo deserializa
@PostMapping("/action02")
public Map<String, Object> action02(@RequestHeader("Content-Type") String type, @RequestBody JsonNode body) {
Map<String, Object> response = new LinkedHashMap<>();
response.put("receivedType", type);
response.put("body", body);
return response;
}
// un solo campo del formulario: @RequestParam, igual que para un parámetro de URL
@PostMapping("/action03")
public String action03(@RequestParam(required = false) String name) {
return "name = [%s]".formatted(name);
}
// los campos del formulario, enlazados y validados por la clase PersonModel
@PostMapping("/action04")
public Map<String, Object> action04(@Valid PersonModel person, BindingResult result) {
Map<String, Object> response = new LinkedHashMap<>();
response.put("person", person);
response.put("valid", !result.hasErrors());
response.put("errors", result.getAllErrors().stream().map(ObjectError::getDefaultMessage).sorted().toList());
return response;
}
}
|
Comentemos este código:
- línea 25: [@PostMapping] asocia la acción con las solicitudes POST, de la misma manera que [@GetMapping] lo hace con las solicitudes GET;
- línea 26: [@RequestHeader("Content-Type")] proporciona el valor de un encabezado de la solicitud: en este caso, el tipo de su cuerpo;
- línea 27: un parámetro de tipo [MultiValueMap<String, String>], anotado con [@RequestParam], recibe todos los parámetros de la solicitud. Un [MultiValueMap] es un diccionario en el que cada clave se asocia con una lista de valores: conserva todos los valores de un parámetro repetido, mientras que el [Map<String, String>] del ejemplo 07 conservaría solo uno;
- Línea 36: [@RequestBody] indica al sistema que lea el cuerpo de la solicitud y lo deserialice, es decir, que lo convierta en un objeto [Java]. El cuerpo debe ser un documento JSON (que es lo que envía un cliente [JavaScript]), leído por la biblioteca [Jackson]. [JsonNode] representa cualquier documento JSON; podríamos haber declarado una clase o un record. Línea 18: en [Jackson] 3, utilizado por [Spring Boot] 4, las clases están en el paquete [tools.jackson.databind] (y ya no en [com.fasterxml.jackson.databind] como en [Jackson] 2);
- líneas 44-45: [@RequestParam] lee un campo de formulario exactamente igual que un parámetro de la URL;
- líneas 50-51: el formulario completo, enlazado y validado por la clase [PersonModel] (una copia, en el paquete [example11.models], de la del ejemplo 08) (un objeto de comando, como en el ejemplo 09);
- línea 55: [sorted()] ordena los mensajes para que el orden de los errores se mantenga constante de una ejecución a otra.
La opción [-d] de [curl] envía una solicitud POST con un cuerpo en el formato de un formulario HTML ([application/x-www-form-urlencoded]):
| curl -i -d "name=martin&age=42" http://localhost:5000/post/action01
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 94
{"receivedType":"application/x-www-form-urlencoded","fields":{"name":["martin"],"age":["42"]}}
|
Cada campo se asocia con una lista de valores, que en este caso contiene un solo valor. El mismo contenido en formato JSON:
| curl -i -H "Content-Type: application/json" -d '{"name":"martin","age":42}' http://localhost:5000/post/action02
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 69
{"receivedType":"application/json","body":{"name":"martin","age":42}}
|
(La opción [-H] de [curl] agrega un encabezado a la solicitud; en [Windows], en el símbolo del sistema, se escribiría [-d "{\"name\":\"martin\",\"age\":42}"]). En el primer caso, la edad es una cadena (un formulario HTML transporta solo texto) y, en el segundo, es un número. [Spring MVC] selecciona el convertidor que lee el cuerpo según el encabezado [Content-Type] de la solicitud. Por lo tanto, una acción [@RequestBody] que espera JSON rechaza un cuerpo de otro tipo y devuelve un error 415 ([Unsupported Media Type], tipo de contenido no admitido):
| curl -i -d "name=martin&age=42" http://localhost:5000/post/action02
|
| HTTP/1.1 415
Accept: application/json, application/*+json
Content-Type: application/json
{"timestamp":"2026-09-25T16:48:45.851Z","status":415,"error":"Unsupported Media Type","message":"Content-Type 'application/x-www-form-urlencoded;charset=UTF-8' is not supported.","path":"/post/action02"}
|
El encabezado de respuesta [Accept] enumera los tipos aceptados. Un cuerpo JSON no válido, en cambio, produce un error 400:
| curl -i -H "Content-Type: application/json" -d '{"name":"martin",' http://localhost:5000/post/action02
|
| HTTP/1.1 400
Content-Type: application/json
{"timestamp":"2026-09-25T16:48:45.879Z","status":400,"error":"Bad Request","message":"JSON parse error: Unexpected end-of-input within/between Object entries","path":"/post/action02"}
|
Las otras dos acciones:
| curl -i -d "name=martin&age=42" http://localhost:5000/post/action03
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 15
name = [martin]
|
| curl -i -d "name=martin&age=42&title=Mme" http://localhost:5000/post/action04
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 89
{"person":{"age":42,"email":null,"name":"martin","title":"Mme"},"valid":true,"errors":[]}
|
| curl -i -d "name=martin&age=200" http://localhost:5000/post/action04
|
| HTTP/1.1 200
Content-Type: application/json
Content-Length: 149
{"person":{"age":200,"email":null,"name":"martin","title":null},"valid":false,"errors":["the age must be between 0 and 150","the title is required"]}
|
[@RequestParam] y los objetos de comando no distinguen la URL del cuerpo: tratan los parámetros de la URL y los campos del formulario como un conjunto único. Por lo tanto, un parámetro presente en ambos lugares recibe dos valores:
| curl -i "http://localhost:5000/post/action03?name=durand" -d "name=martin"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 22
name = [durand,martin]
|
Una acción POST responde con un código de estado 200, igual que una acción GET. En una aplicación HTML, una acción POST responde con una página (el formulario vuelto a mostrar) o con una redirección (véase el ejemplo 20).
3.6. Ejemplo 12: enlace de datos y validación personalizados
El enlace de datos y la validación se pueden ampliar. El caso de estudio los utiliza de manera moderada, pero comprenderlos ayuda a aclarar cómo funciona [Spring MVC].
| 12-custom-binding/
├── src/main/java/example12/
│ ├── controllers/
│ │ └── ExamplesController.java
│ ├── binding/
│ │ ├── DateFrConverter.java
│ │ ├── Language.java
│ │ ├── LanguageResolver.java
│ │ ├── NoSpace.java
│ │ ├── NoSpaceValidator.java
│ │ └── WebConfig.java
│ └── Example12Application.java
├── src/main/resources/
│ └── application.properties
└── pom.xml
|
3.6.1. Un convertidor: DateFrConverter
Para convertir la cadena ["42"] en [int], [Spring MVC] utiliza un convertidor ([Converter]). Proporciona convertidores para todos los tipos comunes; usted puede escribir los suyos. El archivo [binding/DateFrConverter.java]:
| package example12.binding;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.time.format.ResolverStyle;
import org.springframework.core.convert.converter.Converter;
// un conversor: convierte una fecha francesa "23/09/2026" en un LocalDate.
// Se usará para CUALQUIER parámetro de tipo LocalDate (vea WebConfig)
public class DateFrConverter implements Converter<String, LocalDate> {
// uuuu: el año; STRICT: "31/02/2026" se rechaza (y no se convierte al 28 de febrero)
private static final DateTimeFormatter FORMAT =
DateTimeFormatter.ofPattern("dd/MM/uuuu").withResolverStyle(ResolverStyle.STRICT);
@Override
public LocalDate convert(String text) {
try {
return LocalDate.parse(text, FORMAT);
} catch (DateTimeParseException e) {
// fallo: una excepción, que Spring convierte en un error de conversión
throw new IllegalArgumentException("[" + text + "] is not a valid dd/mm/yyyy date");
}
}
}
|
- línea 12: un convertidor implementa la interfaz genérica [Converter<S, T>], donde [S] es el tipo de origen y [T] es el tipo de destino: aquí, de [String] a [LocalDate] (una fecha sin hora);
- líneas 15-16: el formato de fecha, [dd/mm/yyyy]. En modo [STRICT], se rechaza una fecha que no existe (31/02/2026); este modo exige escribir el año como [uuuu] en lugar de [yyyy];
- líneas 19-21: el único método de la interfaz, [convert], devuelve la fecha resultante;
- líneas 22-25: si la conversión falla, el convertidor lanza una excepción. [Spring MVC] produce un error de conversión, igual que con [?age=abc]: error 400 para un [@RequestParam], [typeMismatch] en el [BindingResult] para un campo de un objeto de comando. Nuestra excepción se conserva como la causa del error de conversión: recuperaremos su mensaje en el controlador.
3.6.2. Un argument resolver: la anotación @Language y LanguageResolver
Un parámetro de una acción puede provenir de una fuente distinta de la URL o del formulario. Para cada parámetro de una acción, [Spring MVC] consulta una lista de objetos llamados [argument resolvers] ("resolutores de argumentos"): el primero que declara poder manejar el parámetro proporciona su valor. Así es como funcionan [@RequestParam], [@RequestHeader], [@RequestBody], etc. Usted puede agregar los suyos. Primero, se necesita una forma de identificar los parámetros pertinentes: una anotación "personalizada". El archivo [binding/Language.java]:
| package example12.binding;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
// una anotación "casera": @Language String language. No hace nada por
// sí misma: marca un parámetro, que LanguageResolver sabrá llenar.
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Language {
}
|
- línea 12: [@interface] declara una anotación. Esta anotación no tiene atributos;
- línea 10: [@Target] especifica dónde se puede colocar la anotación: en este caso, solo en un parámetro de método;
- línea 11: [@Retention(RetentionPolicy.RUNTIME)]: la anotación se conserva en el código compilado y se puede leer en tiempo de ejecución. Esto es indispensable para que [Spring MVC] la reconozca.
El archivo [binding/LanguageResolver.java]:
| package example12.binding;
import org.springframework.core.MethodParameter;
import org.springframework.web.bind.support.WebDataBinderFactory;
import org.springframework.web.context.request.NativeWebRequest;
import org.springframework.web.method.support.HandlerMethodArgumentResolver;
import org.springframework.web.method.support.ModelAndViewContainer;
// un "argument resolver": proporciona el valor de los parámetros anotados con @Language,
// leído del encabezado "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr"
public class LanguageResolver implements HandlerMethodArgumentResolver {
// ¿este resolver maneja este parámetro?
@Override
public boolean supportsParameter(MethodParameter parameter) {
return parameter.hasParameterAnnotation(Language.class) && parameter.getParameterType() == String.class;
}
// el valor del parámetro
@Override
public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
NativeWebRequest request, WebDataBinderFactory binderFactory) {
String header = request.getHeader("Accept-Language");
String first = header == null ? "" : header.split(",")[0].trim();
return first.length() >= 2 ? first.substring(0, 2).toLowerCase() : "fr";
}
}
|
- línea 11: un resolutor implementa la interfaz [HandlerMethodArgumentResolver];
- líneas 14-17: [supportsParameter] devuelve [true] para los parámetros que maneja: los marcados con la anotación [@Language] y de tipo [String]. [MethodParameter] describe un parámetro de la acción;
- Líneas 20-26: [resolveArgument] proporciona el valor del parámetro. Entre sus argumentos, [NativeWebRequest] da acceso a la solicitud. Línea 23: el encabezado [Accept-Language], que especifica los idiomas preferidos del usuario. Líneas 24-25: las dos primeras letras del primer idioma, en minúsculas, o ["fr"] si falta el encabezado. El operador [? :] devuelve su segundo operando si la condición es verdadera, y el tercero en caso contrario.
3.6.3. Una restricción de validación: @NoSpace
Una restricción de validación personalizada consta de dos elementos: una anotación y la clase que realiza la validación. El archivo [binding/NoSpace.java]:
| package example12.binding;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import jakarta.validation.Constraint;
import jakarta.validation.Payload;
// una restricción de validación "casera": @NoSpace.
// @Constraint designa la clase que hace la verificación.
@Target({ ElementType.FIELD, ElementType.PARAMETER })
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = NoSpaceValidator.class)
public @interface NoSpace {
// el mensaje de error por defecto
String message() default "the field must not contain any space";
// dos atributos exigidos por el estándar Bean Validation (rara vez usados)
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}
|
- línea 13: la restricción se puede aplicar a un campo de una clase o a un parámetro de un método;
- línea 15: [@Constraint] convierte la anotación en una restricción de [Bean Validation] y especifica la clase que la valida;
- línea 19: el mensaje de error predeterminado. Un atributo de anotación se declara como un método sin parámetros, y [default] le asigna un valor predeterminado: escribiríamos [@NoSpace] o [@NoSpace(message = "...")];
- líneas 22-24: dos atributos exigidos por el estándar: [groups] permite verificar solo un subconjunto de las restricciones, y [payload] permite asociar información a una restricción. No los usamos, pero deben declararse.
El archivo [binding/NoSpaceValidator.java]:
| package example12.binding;
import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;
// la verificación de la restricción @NoSpace, para un valor de tipo String
public class NoSpaceValidator implements ConstraintValidator<NoSpace, String> {
@Override
public boolean isValid(String value, ConstraintValidatorContext context) {
// null se acepta: exigirlo es tarea de @NotNull
return value == null || !value.contains(" ");
}
}
|
- línea 7: la clase de validación implementa [ConstraintValidator<A, T>], donde [A] es la anotación y [T] es el tipo de los valores validados;
- Líneas 10-13: [isValid] devuelve [true] si el valor es aceptable. El valor [null] se acepta, ya que satisface todas las restricciones estándar excepto [@NotNull] y [@NotBlank].
3.6.4. Configuración: WebConfig
El convertidor y el resolutor deben declararse en [Spring MVC]; la restricción se identifica mediante la anotación [@Constraint]. El archivo [binding/WebConfig.java]:
| package example12.binding;
import java.util.List;
import org.springframework.context.annotation.Configuration;
import org.springframework.format.FormatterRegistry;
import org.springframework.web.method.support.HandlerMethodArgumentResolver;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
// WebMvcConfigurer: una clase de configuración que complementa la de Spring MVC.
// Se sobrescriben los métodos que interesan.
@Configuration
public class WebConfig implements WebMvcConfigurer {
// los conversores: String -> LocalDate
@Override
public void addFormatters(FormatterRegistry registry) {
registry.addConverter(new DateFrConverter());
}
// los "argument resolvers": los parámetros @Language
@Override
public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
resolvers.add(new LanguageResolver());
}
}
|
- Línea 12: [@Configuration] designa una clase de configuración: [Spring Boot] la descubre al iniciar (está en un subpaquete del que contiene la clase [Example12Application]), crea una instancia de ella y la utiliza;
- Línea 13: la interfaz [WebMvcConfigurer] permite ampliar la configuración de [Spring MVC] establecida por [Spring Boot], sin reemplazarla. Tiene muchos métodos, que de manera predeterminada no hacen nada; sobrescribimos ([@Override]) los que nos interesan;
- líneas 16-19: [addFormatters] registra convertidores. [DateFrConverter] se utilizará para cualquier parámetro de tipo [LocalDate] de la aplicación;
- Líneas 22-25: [addArgumentResolvers] agrega resolutores a la lista de los de [Spring MVC].
3.6.5. El controlador
El archivo [controllers/ExamplesController.java]:
| package example12.controllers;
import java.time.LocalDate;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.method.annotation.HandlerMethodValidationException;
import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
import example12.binding.Language;
import example12.binding.NoSpace;
@RestController
@RequestMapping("/examples")
public class ExamplesController {
// /examples/schedule?day=23/09/2026: un conversor personalizado (DateFrConverter)
@GetMapping("/schedule")
public String schedule(@RequestParam LocalDate day) {
return "schedule for the day [" + day + "]";
}
// /examples/hello: un parámetro que no proviene de la URL, sino de un encabezado
@GetMapping("/hello")
public String hello(@Language String language) {
return "en".equals(language) ? "Hello!" : "Bonjour !";
}
// /examples/search?keyword=spring: una restricción de validación personalizada,
// colocada directamente sobre un parámetro de la acción
@GetMapping("/search")
public String search(@RequestParam(required = false) @NoSpace String keyword) {
return "search for [" + keyword + "]";
}
// errores
// @ExceptionHandler: un método del controlador que convierte una excepción lanzada
// por una de sus acciones (o por el enlace de sus parámetros) en una respuesta
// una conversión imposible (DateFrConverter lanzó una excepción)
@ExceptionHandler
@ResponseStatus(HttpStatus.BAD_REQUEST)
public String conversion(MethodArgumentTypeMismatchException e) {
// la excepción original, la de DateFrConverter: su mensaje es nuestro
return e.getMostSpecificCause().getMessage();
}
// un parámetro que viola una restricción de validación (@NoSpace)
@ExceptionHandler
@ResponseStatus(HttpStatus.BAD_REQUEST)
public String validation(HandlerMethodValidationException e) {
return e.getAllErrors().get(0).getDefaultMessage();
}
}
|
- línea 24: un parámetro normal de tipo [LocalDate]: nada indica que deba utilizarse [DateFrConverter]; lo determina su tipo;
- línea 30: el parámetro [language] lo proporciona [LanguageResolver], mediante la anotación [@Language];
- línea 37: una restricción de validación también puede aplicarse directamente a un parámetro de la acción (aquí, junto con [@RequestParam]). No es necesario [@Valid]: [Spring MVC] valida automáticamente los parámetros que tienen una restricción. Si la validación falla, lanza la excepción [HandlerMethodValidationException];
- líneas 46-51: un método anotado con [@ExceptionHandler] es un manejador de excepciones: si una acción del controlador, o el enlace de sus parámetros, lanza una excepción del mismo tipo que su parámetro (aquí, [MethodArgumentTypeMismatchException], un error de conversión), [Spring MVC] lo llama en lugar de generar su propia respuesta de error. Lo que devuelve se convierte en la respuesta, con el código establecido por [@ResponseStatus]: 400 ([HttpStatus.BAD_REQUEST]). Línea 50: [getMostSpecificCause()] devuelve la excepción original, la lanzada por [DateFrConverter], que contiene nuestro mensaje;
- Líneas 54-58: lo mismo se aplica al error de validación de un parámetro. [getAllErrors()] devuelve la lista de errores, de la cual conservamos el mensaje del primero.
Sin estos dos manejadores, la respuesta sería el error JSON de [Spring Boot], con un mensaje técnico en inglés para la fecha, que no incluye el nuestro. Un manejador de excepciones se aplica únicamente a su controlador; en el ejemplo 24 veremos cómo escribir uno para toda la aplicación ([@ControllerAdvice]).
Los resultados:
| curl -i "http://localhost:5000/examples/schedule?day=23/09/2026"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 33
schedule for the day [2026-09-23]
|
| curl -i "http://localhost:5000/examples/schedule?day=2026-09-23"
|
| HTTP/1.1 400
Content-Type: text/plain;charset=UTF-8
Content-Length: 43
[2026-09-23] is not a valid dd/mm/yyyy date
|
| curl -i "http://localhost:5000/examples/schedule?day=31/02/2026"
|
| HTTP/1.1 400
Content-Type: text/plain;charset=UTF-8
Content-Length: 43
[31/02/2026] is not a valid dd/mm/yyyy date
|
Una fecha [LocalDate] se escribe como [2026-09-23] al convertirse en cadena (formato ISO). El idioma:
| curl -i -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:5000/examples/hello
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 9
Bonjour !
|
| curl -i -H "Accept-Language: en-US,en;q=0.9" http://localhost:5000/examples/hello
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 6
Hello!
|
La restricción [@NoSpace]:
| curl -i "http://localhost:5000/examples/search?keyword=spring"
|
| HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 19
search for [spring]
|
| curl -i "http://localhost:5000/examples/search?keyword=spring%20mvc"
|
| HTTP/1.1 400
Content-Type: text/plain;charset=UTF-8
Content-Length: 36
the field must not contain any space
|
([%20] es la codificación de un espacio en una URL)
3.6.6. Conclusión
El modelo de la acción se construye enlazando datos de la solicitud: parámetros de la URL y campos de formulario ([@RequestParam], objeto de comando), el cuerpo JSON ([@RequestBody]), encabezados ([@RequestHeader]) y todo lo que pueda proporcionar un resolutor personalizado. Los valores se convierten al tipo del parámetro y luego se validan según las restricciones de [Bean Validation] cuando el modelo está anotado con [@Valid]. Un error de conversión con un [@RequestParam], o un modelo no válido sin un [BindingResult], produce un error 400 sin ejecutar la acción: esto es adecuado para un servidor JSON. Para una aplicación HTML, el formulario es un JavaBean anotado con [@Valid], seguido de un parámetro [BindingResult] que la acción consulta (ejemplo 09), para poder volver a mostrar el formulario con sus errores. Este es el tema del capítulo siguiente.