...
← Curs Spring Boot și REST API: toate lecțiile
Lecția 7 · Parametri

Parametri de interogare cu @RequestParam

Când cauți ceva pe un site, adresa se termină des cu ?q=java&pagina=2. Partea de după semnul întrebării este query string-ul, iar Spring ți-l dă prin @RequestParam. Înveți parametri obligatorii, valori implicite, parametri opționali și când folosești @RequestParam în loc de @PathVariable.

Query string-ul

După cale poate urma un ? și o listă de perechi nume=valoare, separate prin &. Ordinea lor nu contează.

GET /produse?categorie=laptopuri&pagina=2
         └─ calea  └─ query string: categorie=laptopuri, pagina=2

Cu @RequestParam pe un parametru al metodei, Spring caută în query string o pereche cu același nume și convertește valoarea la tipul parametrului, ca la @PathVariable:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@RestController
class CautareController {
    @GetMapping("/produse")
    String produse(@RequestParam String categorie, @RequestParam int pagina) {
        return "Categoria " + categorie + ", pagina " + pagina;
    }
}

// > GET /produse?categorie=laptopuri&pagina=2
// > GET /produse?pagina=1&categorie=mouse
Tomcat started on port 8080 (http)
Started Application
GET /produse?categorie=laptopuri&pagina=2 → 200
Categoria laptopuri, pagina 2
GET /produse?pagina=1&categorie=mouse → 200
Categoria mouse, pagina 1

Obligatoriu sau cu valoare implicită

Un @RequestParam simplu este obligatoriu: dacă lipsește, Spring răspunde cu 400. Cu defaultValue, parametrul devine opțional și primește valoarea implicită când lipsește. defaultValue se scrie mereu ca text, chiar dacă parametrul este număr sau boolean; Spring îl convertește.

/* application.properties
server.error.include-message=always
*/

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@RestController
class CautareController {
    @GetMapping("/produse")
    String produse(@RequestParam String categorie,
                   @RequestParam(defaultValue = "1") int pagina,
                   @RequestParam(defaultValue = "false") boolean doarInStoc) {
        return categorie + " | pagina " + pagina + " | doar în stoc: " + doarInStoc;
    }
}

// > GET /produse?categorie=laptopuri
// > GET /produse?categorie=laptopuri&pagina=3&doarInStoc=true
// > GET /produse
Tomcat started on port 8080 (http)
Started Application
GET /produse?categorie=laptopuri → 200
laptopuri | pagina 1 | doar în stoc: false
GET /produse?categorie=laptopuri&pagina=3&doarInStoc=true → 200
laptopuri | pagina 3 | doar în stoc: true
GET /produse → 400
{"status":400,"error":"Bad Request","message":"Required request parameter 'categorie' for method parameter type String is not present","path":"/produse"}

Prima cerere folosește valorile implicite (pagina 1, false). A doua le dă pe toate. A treia nu are categorie, care este obligatoriu, deci 400, iar mesajul (vizibil datorită setării din blocul /* application.properties */) spune exact ce lipsește: „Required request parameter 'categorie' ... is not present”.

Parametri opționali fără valoare implicită

Uneori nu există o valoare implicită potrivită: vrei doar să știi dacă parametrul a fost trimis. Ai două variante:

  • @RequestParam Optional<String> status: primești un Optional, gol când parametrul lipsește (orElse dă o valoare de rezervă);
  • @RequestParam(required = false) Integer an: primești null când lipsește. Folosește **Integer, nu int**, pentru că int nu poate fi null.
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import java.util.Optional;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@RestController
class FiltruController {
    @GetMapping("/comenzi")
    String comenzi(@RequestParam Optional<String> status,
                   @RequestParam(required = false) Integer an) {
        String text = "Comenzi " + status.map(s -> "cu statusul " + s).orElse("cu orice status");
        if (an != null) {
            text = text + " din " + an;
        }
        return text;
    }
}

// > GET /comenzi
// > GET /comenzi?status=livrata
// > GET /comenzi?status=anulata&an=2025
Tomcat started on port 8080 (http)
Started Application
GET /comenzi → 200
Comenzi cu orice status
GET /comenzi?status=livrata → 200
Comenzi cu statusul livrata
GET /comenzi?status=anulata&an=2025 → 200
Comenzi cu statusul anulata din 2025
Verifică null înainte să-l folosești

Un parametru required = false care lipsește este null. Dacă apelezi o metodă pe el fără if (an != null), programul se oprește cu NullPointerException, iar clientul primește 500. Optional sau defaultValue te scutesc de grija asta.

@PathVariable sau @RequestParam?

@PathVariable@RequestParam
unde stăîn cale: /produse/15după ?: /produse?categorie=mouse
la ce foloseșteidentifică o resursă anumefiltrează, sortează, alege pagina
lipseștealtă rută (de obicei 404)400 sau valoarea implicită
exemplu/comenzi/2031/comenzi?status=livrata&an=2025

Regula practică: dacă fără valoarea respectivă adresa nu mai are sens („produsul cu id-ul...”), pune-o în cale. Dacă este o opțiune a listei, pune-o în query string. Site-urile de anunțuri (OLX, eMAG) folosesc query string-ul pentru toate filtrele: preț, oraș, ordonare.

Greșeli frecvente

  • Nume diferit în URL și în cod: ?cuvant=java nu ajunge la @RequestParam String q. Folosește același nume sau @RequestParam("cuvant") String q.
  • **required = false cu int**: când parametrul lipsește, Spring nu poate pune null într-un int; folosește Integer sau defaultValue.
  • Uiți că valorile sunt text: defaultValue = 10 nu compilează; scrie defaultValue = "10".
  • Spații și caractere speciale: în URL-uri reale, spațiul se scrie %20 sau + (?q=spring+boot); browserul și Postman fac asta automat.

Pe scurt

  • Query string-ul este partea de după ?: perechi nume=valoare separate prin &.
  • @RequestParam simplu este obligatoriu; lipsa lui dă 400.
  • defaultValue = "..." face parametrul opțional, cu o valoare implicită.
  • Optional<T> sau required = false (cu tip wrapper, Integer) pentru parametri opționali fără valoare implicită.
  • @PathVariable identifică, @RequestParam filtrează.
Exercițiul tău

Construiește căutarea magazinului: GET /cauta primește parametrul obligatoriu q și parametrul limita (implicit 10) și răspunde cu textul Caut „q” (maxim N rezultate), de exemplu Caut „java” (maxim 3 rezultate). Laboratorul trimite /cauta?q=java&limita=3, /cauta?q=sql și /cauta (fără q, deci 400).

  • Adaugă o metodă cu @GetMapping("/cauta").
  • Primește @RequestParam String q (obligatoriu).
  • Primește limita ca int, cu defaultValue = "10".
  • Întoarce textul cu ghilimelele românești „ și ” în jurul lui q.
return "Caut „" + q + "” (maxim " + limita + " rezultate)";

Soluția exercițiului

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@RestController
class CautareController {
    @GetMapping("/cauta")
    String cauta(@RequestParam String q, @RequestParam(defaultValue = "10") int limita) {
        return "Caut „" + q + "” (maxim " + limita + " rezultate)";
    }
}
Excelent! Continuă cu lecția următoare →
Application.javaSpring Boot
ConsolăSe încarcă...
Mediul de lucru se încarcă. Poți citi lecția între timp.
Rulează codul cu butonul de sus sau cu Ctrl + Enter / Cmd + Enter.
Parcursul tău Primul tău API cu Spring Boot Lecția 7 · Parametri de interogare cu @RequestParam
Progres 0% 0 din 20
Lecția curentă 7 / 18 Parametri