La anotación @RequestParam es un componente fundamental en el desarrollo de aplicaciones web con Spring Framework, especialmente dentro de Spring MVC. Permite mapear los parámetros de una petición HTTP, ya sean de la cadena de consulta (query string) en solicitudes GET o del cuerpo de la solicitud en formularios POST (x-www-form-urlencoded), directamente a los argumentos de los métodos de un controlador.

1. Fundamento de @RequestParam

@RequestParam facilita la extracción de datos enviados por el cliente como parte de la URL o del cuerpo de la solicitud. Su propósito principal es vincular un parámetro de petición web a un argumento del método de un controlador.

• Se utiliza para capturar valores de la cadena de consulta (por ejemplo, /api/recursos?id=123) y datos de formularios.
• Los valores de los parámetros se convierten automáticamente al tipo de dato del argumento del método (ej. String a Integer).
• Permite definir si un parámetro es obligatorio y especificar un valor predeterminado si no está presente en la solicitud.

2. Ejemplo Básico de Uso

Consideremos un escenario donde necesitamos obtener un identificador de usuario de la URL. Si un cliente accede a /api/usuarios/buscar?identificador=U456, podemos capturar el valor "U456" con @RequestParam.

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("/api/usuarios")
public class GestorUsuariosController {

    @GetMapping("/buscar")
    public String obtenerDetallesUsuario(@RequestParam String identificador) {
        // En un caso real, aquí se consultaría una base de datos o servicio
        return "Solicitud recibida para el usuario con ID: " + identificador;
    }
}

En este ejemplo, si la solicitud no incluye el parámetro identificador, Spring MVC lanzará una excepción MissingServletRequestParameterException, ya que por defecto, todos los parámetros con @RequestParam son requeridos.

3. Atributos Clave de @RequestParam

La anotación @RequestParam ofrece atributos para controlar su comportamiento de manera más flexible:

• name (o value): Define el nombre del parámetro en la petición HTTP. Si no se especifica, Spring asume que el nombre del parámetro en la petición es igual al nombre del argumento del método.
• required: Un valor booleano (por defecto true) que indica si el parámetro es indispensable.
• defaultValue: Proporciona un valor por defecto que se utilizará si el parámetro no está presente en la solicitud. Este atributo es mutuamente excluyente con required = true (es decir, si se usa defaultValue, required se comporta como false implícitamente).

Veamos un ejemplo que utiliza estos atributos para gestionar una búsqueda de productos:

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("/api/catalogo")
public class CatalogoProductosController {

    @GetMapping("/listar")
    public String obtenerProductos(
            @RequestParam(name = "categoria", required = false, defaultValue = "general") String nombreCategoria,
            @RequestParam(name = "cantidad", defaultValue = "10") int limiteResultados) {

        return String.format("Mostrando %d productos de la categoría: %s", limiteResultados, nombreCategoria);
    }
}

En este caso:

• Si la solicitud es /api/catalogo/listar, el resultado será "Mostrando 10 productos de la categoría: general".
• Si la solicitud es /api/catalogo/listar?categoria=electronica, el resultado será "Mostrando 10 productos de la categoría: electronica".
• Si la solicitud es /api/catalogo/listar?cantidad=20&categoria=hogar, el resultado será "Mostrando 20 productos de la categoría: hogar".

4. Casos Comunes de Errores y Soluciones

Durante el desarrollo, pueden surgir problemas al usar @RequestParam:

• Parámetro Faltante (MissingServletRequestParameterException): Ocurre cuando un parámetro marcado como required=true (o por defecto) no se incluye en la solicitud.

  Solución: Establecer required = false si el parámetro es opcional, o proporcionar un defaultValue.

• Incompatibilidad de Tipos (TypeMismatchException): Si el valor del parámetro en la solicitud no puede conevrtirse al tipo del argumento del método (ej. "abc" a int).

  Solución: Asegurarse de que los tipos de datos coincidan o implementar un conversor de tipos personalizado si es necesario.

• Desajuste de Nombres: Si el nombre del parámetro en la solicitud difiere del nombre del argumento del método y no se ha especificado explícitamente el atributo name (o value) en @RequestParam.

  Solución: Asegurar que el nombre del argumento del método sea idéntico al del parámetro en la URL, o usar @RequestParam(name = "nombre_del_parametro_en_url").

5. Flujo de Procesamiento de Parámetros

Cuando un cliente envía una solicitud HTTP que incluye parámetros, Spring sigue una serie de pasos para vincularlos a los métodos del controlador:

1. El cliente envía una petición HTTP (ej. GET /api/recursos?query=valor).
2. El DispatcherServlet de Spring recibe la solicitud.
3. El DispatcherServlet identifica el controlador y el método adecuados para manejar la sloicitud.
4. Para cada argumento del método anotado con @RequestParam, Spring busca el parámetro correspondiente en la cadena de consulta o en el cuerpo de la solicitud.
5. Si el parámetro se encuentra, Spring intenta convertir su valor de tipo String al tipo de dato del argumento del método.
6. Si la conversión es exitosa y el parámetro es obligatorio, o si tiene un valor por defecto, Spring asigna el valor al argumento.
7. Una vez que todos los argumentos están preparados, Spring invoca el método del controlador.
8. El método del controlador ejecuta su lógica y devuelve una respuesta.

6. Diferencia con @PathVariable

Es común confundir @RequestParam con @PathVariable. Aunque ambos se utilizan para extraer valores de la URL, su propósito y origen son distintos:

• @RequestParam: Extrae valores de la cadena de consulta (después de ?) o de datos de formulario. Representa datos adicionales o filtros (ej. /productos?categoria=electronica).
• @PathVariable: Extrae valores de segmentos de la ruta URI. Representa una parte integral del recurso o su identificador (ej. /usuarios/{id} donde {id} es una variable de ruta).

La elección entre uno y otro depende de la estructura semántica que se desee dar a la URL para representar los recursos y sus acciones.