Spring MVC: Diferencia entre @PathVariable, @RequestParam y @RequestBody

Cuando trabajamos con aplicaciones web en Spring Boot, uno de los aspectos clave es cómo recibir datos en los controladores REST. En este contexto, @PathVariable, @RequestParam y @RequestBody son tres anotaciones fundamentales que nos permiten capturar y utilizar datos enviados por el cliente en diferentes formatos. Aunque su propósito es similar (obtener datos desde la petición HTTP), cada una tiene un uso específico y características particulares.

En este post vamos a ver de forma clara y estructurada para qué sirve cada una, sus ventajas e inconvenientes, y cómo utilizarlas correctamente con ejemplos prácticos. Al final, te mostraré un ejemplo donde las combinamos todas en un mismo controlador.

¿Qué es @PathVariable?

La anotación @PathVariable se utiliza para extraer valores directamente de la URL. Es decir, forma parte de la ruta definida en el @RequestMapping o el @GetMapping. Básicamente lo que hace es recoger la entrada en formato "Decoded".

¿Cuándo se usa?

Cuando quieres que parte de la ruta se convierta en un parámetro que tu método reciba. Es muy útil para rutas con identificadores o categorías.

🔎 Ejemplo básico

@GetMapping("/usuarios/{id}")
public String obtenerUsuario(@PathVariable int id) {
    return "Usuario con ID: " + id;
}

El funcionamiento será:

Petición: /usuarios/42,
Método: el valor 42 se inyecta en el parámetro id.

✅ Ventajas

Muy legible: la URL refleja claramente el recurso solicitado.
RESTful: encaja perfectamente con el diseño de APIs REST.

❌ Inconvenientes

No es adecuado para datos opcionales o filtros complejos.
La estructura de la URL debe coincidir estrictamente con la definición.

¿Qué es @RequestParam?

La anotación @RequestParam se utiliza para obtener valores de los parámetros de la URL, es decir, los que vienen después del signo "?". Básicamente lo que hace es recoger la entrada en formato "Encoded".

¿Cuándo se usa?

Esta anotación se utiliza cuando quieres capturar datos de tipo clave-valor enviados como parte de la query string o incluso de un formulario.

🔎 Ejemplo básico

@GetMapping("/buscar")
public String buscarUsuario(
    @RequestParam String nombre,
    @RequestParam String apellido)
{
    return "Buscando al usuario: " + nombre + " " + apellido;
}

El funcionamiento será:

Petición: /buscar?nombre=Ana&apellido=Aldeguer
Respuesta: Buscando al usuario: Ana Aldeguer.

✅ Ventajas

Perfecto para filtros, ordenaciones y parámetros opcionales.
Se disponen de atributos que permiten usar valores por defecto ("defaultValue") y marcar parámetros como opcionales ("required").

❌ Inconvenientes

Menos expresivo que @PathVariable para recursos.
Más expuesto a errores si no se validan bien los datos recibidos.

🔎 Ejemplo con valor por defecto

En este ejemplo, si en la URL no se envía el parámetro indicado, entonces Spring le asignará el valor por defecto indicado en el atributo "defaultValue" ("todos"). Por otra parte, en el ejemplo también se está indicando que el parámetro de entrada es opcional mediante el atributo "required" ("false"), por lo que no es obligatorio que se envíe en la URL invocante.


@GetMapping("/buscar")
public String buscar(
    @RequestParam(value="tipo", defaultValue="todos", required=false) String tipo)
{
    return "Buscando tipo: " + tipo;
}

¿Qué es @RequestBody?

La anotación @RequestBody permite capturar el cuerpo completo de la petición HTTP, y convertirlo directamente a un objeto Java.

¿Cuándo se usa?

Cuando se envían datos complejos en formato JSON, XML o texto plano. Es el estándar para peticiones POST, PUT o PATCH donde se envía una entidad completa.

🔎 Ejemplo básico

Supongamos que tenemos una clase "Usuario":

public class Usuario {
    private String nombre;
    private int edad;
    // getters y setters
}

El controlador podría ser algo como lo siguiente:

@PostMapping("/usuarios")
public String crearUsuario(@RequestBody Usuario usuario) {
    return "Usuario creado: " + usuario.getNombre();
}

Y la petición desde el cliente sería un JSON como el siguiente:

{
  "nombre": "Lucía",
  "edad": 30
}

✅ Ventajas

Ideal para objetos complejos.
Totalmente integrado con JSON y librerías como Jackson o Gson.

❌ Inconvenientes

Sólo se puede usar uno por método (el cuerpo se puede leer una única vez).
Necesita encabezados adecuados: "Content-Type: application/json".
Requiere clases bien definidas para el binding de datos.

Ejemplo combinando las tres anotaciones

Una vez visto lo anterior, vamos ahora a intentar crear un ejemplo en el que se haga uso de los tres tipos de anotaciones revisados. Supongamos que tenemos un servicio para actualizar datos de un usuario con un ID determinado, pero queremos recibir también una opción adicional ("notificar") como parámetro y los nuevos datos del usuario como JSON.

➕ Clase de la entidad

 

public class Usuario {
    private String nombre;
    private int edad;
    // getters y setters
}

➕ Controlador

El controlador con las anotaciones combinadas podría ser implementado de varias formas, pero una solución factible sería algo así como lo siguiente:

  

@PutMapping("/usuarios/{id}")
public String actualizarUsuario(
    @PathVariable Long id,
    @RequestParam(defaultValue = "false") boolean notificar,
    @RequestBody Usuario datos) 
{
    // Aquí actualizaríamos los datos en la base
    String respuesta = "Usuario con ID " + id + " actualizado. Nombre: " + datos.getNombre();
    if (notificar) {
        respuesta += " Se ha enviado una notificación.";
    }
    return respuesta;
}

➕ Petición HTTP de ejemplo

 
PUT /usuarios/7?notificar=true
Content-Type: application/json

{
  "nombre": "Sofía",
  "edad": 29
}

➕ Resultado esperado

 
Usuario con ID 7 actualizado. Nombre: Sofía. Se ha enviado una notificación.

Este ejemplo refleja perfectamente cómo se pueden combinar las tres anotaciones para obtener una petición bien estructurada y con muchos datos.

Conclusión

En Spring Web saber cuándo usar @PathVariable, @RequestParam y @RequestBody es esencial para diseñar APIs claras, eficaces y bien estructuradas. Cada anotación cumple un papel diferente:

Usa @PathVariable para identificar recursos en la URL.
Usa @RequestParam para valores opcionales, filtros o query strings.
Usa @RequestBody para recibir estructuras complejas como JSON.

Y lo mejor es que las tres anotaciones pueden ser combinadas, en caso de necesidad. Esto te permite construir APIs RESTful robustas sin complicarte la vida.

Si estás construyendo un backend moderno con Spring Boot, dominar estas tres anotaciones es un paso esencial para gestionar peticiones HTTP de forma limpia y elegante.

¡Nos vemos en el siguiente post!

Saludos.

Buscar este blog

Universo Java