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

Variabile în cale cu @PathVariable

Un magazin are mii de produse, dar nu scrii câte o metodă pentru fiecare. Scrii una singură, pentru /produse/{id}, iar Spring îți dă id-ul din adresă ca parametru. În lecția aceasta înveți @PathVariable: segmente variabile, conversia automată la numere și ce se întâmplă când valoarea nu e bună.

Un segment variabil în cale

Până acum toate căile au fost fixe. Cu acolade, {id}, marchezi un segment care se poate schimba. Orice valoare ar fi acolo, cererea ajunge la aceeași metodă, iar @PathVariable pune valoarea într-un parametru Java.

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 ComandaController {
    @GetMapping("/comenzi/{id}")
    String comanda(@PathVariable long id) {
        return "Comanda numărul " + id;
    }
}

// > GET /comenzi/15
// > GET /comenzi/2031
Tomcat started on port 8080 (http)
Started Application
GET /comenzi/15 → 200
Comanda numărul 15
GET /comenzi/2031 → 200
Comanda numărul 2031
1
{id} din @GetMapping("/comenzi/{id}") se potrivește cu orice segment: 15, 2031.
2
@PathVariable long id ia valoarea segmentului și o convertește la long. Numele parametrului (id) este același cu cel din acolade.
3
În metodă folosești id ca pe orice variabilă Java.
Importul cu steluță

De aici înainte folosim import org.springframework.web.bind.annotation.*;, care aduce dintr-o dată toate adnotările web (@RestController, @GetMapping, @PathVariable și celelalte). Mediile de dezvoltare (IntelliJ) adaugă și ele astfel de importuri.

Mai multe variabile și alte nume

O cale poate avea mai multe variabile. Fiecare primește parametrul ei, iar tipul Java decide conversia: String rămâne text, int/long devin numere. Dacă vrei alt nume pentru parametrul Java, scrii numele din acolade în adnotare: @PathVariable("oras") String numeOras.

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 CatalogController {
    @GetMapping("/categorii/{categorie}/produse/{id}")
    String produs(@PathVariable String categorie, @PathVariable int id) {
        return "Produsul " + id + " din categoria " + categorie;
    }

    @GetMapping("/orase/{oras}")
    String oras(@PathVariable("oras") String numeOras) {
        String termen = numeOras.length() > 4 ? "2 zile" : "o zi";
        return "Livrăm în " + numeOras + " în " + termen;
    }
}

// > GET /categorii/laptopuri/produse/42
// > GET /orase/Iasi
// > GET /orase/Timisoara
Tomcat started on port 8080 (http)
Started Application
GET /categorii/laptopuri/produse/42 → 200
Produsul 42 din categoria laptopuri
GET /orase/Iasi → 200
Livrăm în Iasi în o zi
GET /orase/Timisoara → 200
Livrăm în Timisoara în 2 zile
Tip parametruExemplu de valoare acceptată
Stringorice text: laptopuri, Iasi
int, longnumere întregi: 42, 2031
doublenumere cu zecimale: 9.99
booleantrue / false

Când valoarea nu se poate converti

Ce se întâmplă cu GET /comenzi/abc, când parametrul este long? Textul abc nu este un număr, deci Spring nu poate apela metoda și răspunde cu 400 Bad Request: clientul a trimis o cerere greșită. Metoda ta nici nu rulează.

Ca să vezi și motivul, exemplul de mai jos pornește aplicația cu o setare care pune mesajul erorii în răspuns (blocul /* application.properties ... */ de la început; despre acest fișier de configurare afli în lecția 15):

/* 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 ComandaController {
    @GetMapping("/comenzi/{id}")
    String comanda(@PathVariable long id) {
        return "Comanda numărul " + id;
    }
}

// > GET /comenzi/abc
Tomcat started on port 8080 (http)
Started Application
GET /comenzi/abc → 400
{"status":400,"error":"Bad Request","message":"Method parameter 'id': Failed to convert value of type 'java.lang.String' to required type 'long'; For input string: \"abc\"","path":"/comenzi/abc"}

Mesajul spune: parametrul id nu s-a putut converti din String în long, pentru textul abc. Fără setarea aceea, răspunsul conține doar status, error și path, iar mesajul apare în jurnalul serverului. Așa este și în producție: nu arăți clienților detaliile interne.

Exemple reale

AplicațiaRută cu variabile
magazin onlineGET /produse/{id}, GET /categorii/{slug}
curieratGET /colete/{awb} (AWB-ul coletului)
bancăGET /conturi/{iban}/tranzactii
GitHubGET /repos/{proprietar}/{repo}

Variabila din cale identifică o resursă: un produs anume, un colet anume. Pentru filtre și opțiuni (căutare, pagină, ordonare) se folosesc parametrii de interogare, în lecția următoare.

Greșeli frecvente

  • Nume diferite: @GetMapping("/produse/{id}") cu @PathVariable long cod nu se potrivesc. Folosește același nume sau scrie-l în adnotare: @PathVariable("id") long cod.
  • **Uiți @PathVariable**: parametrul nu este legat de cale și Spring nu știe de unde să-l ia.
  • Uiți acoladele: @GetMapping("/produse/id") acceptă doar textul fix id.
  • Tipul greșit: dacă id-urile pot conține litere (de exemplu un AWB), folosește String, altfel clienții primesc 400.

Pe scurt

  • {nume} în cale marchează un segment variabil; @PathVariable îl pune într-un parametru.
  • Spring convertește automat valoarea la tipul parametrului (long, int, String...).
  • O cale poate avea mai multe variabile; numele din acolade trebuie să se potrivească cu parametrul.
  • O valoare care nu se poate converti dă 400 Bad Request, iar metoda nu rulează.
Exercițiul tău

Adaugă două rute cu variabile în cale. GET /produse/{id} răspunde cu Produsul cu id-ul N (unde N este id-ul din adresă, ca număr). GET /utilizatori/{nume}/salut răspunde cu Salut, Nume!. Laboratorul trimite /produse/7, /utilizatori/Ana/salut și /produse/abc (care trebuie să primească 400, pentru că id-ul este un număr).

  • Adaugă metoda pentru @GetMapping("/produse/{id}") cu un parametru @PathVariable long id.
  • Adaugă metoda pentru @GetMapping("/utilizatori/{nume}/salut") cu un parametru @PathVariable String nume.
  • Construiește textele din parametri, nu le scrie fix.
return "Produsul cu id-ul " + id; și return "Salut, " + nume + "!";

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 MagazinController {
    @GetMapping("/produse/{id}")
    String produs(@PathVariable long id) {
        return "Produsul cu id-ul " + id;
    }

    @GetMapping("/utilizatori/{nume}/salut")
    String salut(@PathVariable String nume) {
        return "Salut, " + nume + "!";
    }
}
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 6 · Variabile în cale cu @PathVariable
Progres 0% 0 din 20
Lecția curentă 6 / 18 Parametri