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=2Cu @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=mouseTomcat 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 /produseTomcat 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=2025Tomcat 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
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/15 | după ?: /produse?categorie=mouse |
| la ce folosește | identifică o resursă anume | filtrează, sortează, alege pagina |
| lipsește | altă 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ă.
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.
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)";
}
} 