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

Prefixul comun cu @RequestMapping

Când toate rutele unui controller încep la fel (/api/produse/...), nu mai scrii prefixul de fiecare dată. Îl pui o singură dată pe clasă, cu @RequestMapping. Afli și de ce API-urile reale încep cu /api și, des, cu o versiune (/api/v1).

Problema: același început peste tot

Uită-te la aceste rute dintr-un controller de produse:

@GetMapping("/api/produse")
@GetMapping("/api/produse/noi")
@GetMapping("/api/produse/reduceri")

Partea /api/produse se repetă. Dacă mâine echipa decide să schimbe adresele în /api/v1/produse, trebuie să modifici fiecare linie și e ușor să uiți una. Soluția: scrii prefixul o singură dată, pe clasă.

@RequestMapping pe clasă

@RequestMapping("/prefix") pus deasupra clasei se adaugă în fața căii fiecărei metode. Un @GetMapping fără argument înseamnă chiar prefixul.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

@RestController
@RequestMapping("/api/produse")
class ProdusController {
    @GetMapping
    String toate() {
        return "Laptop, Mouse, Tastatură";
    }

    @GetMapping("/noi")
    String noi() {
        return "Mouse Silent";
    }

    @GetMapping("/reduceri")
    String reduceri() {
        return "Tastatură -20%";
    }
}

// > GET /api/produse
// > GET /api/produse/noi
// > GET /api/produse/reduceri
// > GET /noi
Tomcat started on port 8080 (http)
Started Application
GET /api/produse → 200
Laptop, Mouse, Tastatură
GET /api/produse/noi → 200
Mouse Silent
GET /api/produse/reduceri → 200
Tastatură -20%
GET /noi → 404
{"status":404,"error":"Not Found","path":"/noi"}
Pe clasăPe metodăRuta finală
/api/produse@GetMappingGET /api/produse
/api/produse@GetMapping("/noi")GET /api/produse/noi
/api/produse@GetMapping("/reduceri")GET /api/produse/reduceri

GET /noi dă 404: calea metodei nu există singură, ci doar lipită după prefix.

Slash-urile se potrivesc singure

Spring unește corect prefixul și calea: "/api/produse" + "/noi" = /api/produse/noi. Scrie fiecare parte cu slash la început și fără slash la final, ca să fie clar și uniform.

De ce /api și /api/v1

  • **/api** separă adresele care întorc date (JSON) de paginile site-ului. Pe același domeniu, magazin.ro/produse poate fi pagina pentru oameni, iar magazin.ro/api/produse datele pentru aplicație.
  • Versiunea (/api/v1, /api/v2) îți permite să schimbi formatul răspunsurilor fără să strici aplicațiile vechi. Aplicația mobilă instalată acum un an folosește încă v1, iar cea nouă folosește v2.
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

@RestController
@RequestMapping("/api/v1/comenzi")
class ComandaControllerV1 {
    @GetMapping
    String toate() {
        return "v1: 2 comenzi";
    }
}

@RestController
@RequestMapping("/api/v2/comenzi")
class ComandaControllerV2 {
    @GetMapping
    String toate() {
        return "v2: [{\"id\":1},{\"id\":2}]";
    }
}

// > GET /api/v1/comenzi
// > GET /api/v2/comenzi
Tomcat started on port 8080 (http)
Started Application
GET /api/v1/comenzi → 200
v1: 2 comenzi
GET /api/v2/comenzi → 200
v2: [{"id":1},{"id":2}]

Două controllere, două prefixe: fiecare versiune trăiește separat. Băncile și firmele de telecom păstrează astfel versiunile vechi luni sau ani, până când toți clienții trec pe cea nouă.

@RequestMapping și pe metode

@RequestMapping poate sta și pe o metodă, cu metoda HTTP scrisă explicit. @GetMapping este de fapt o scurtătură pentru forma aceasta:

@RequestMapping(value = "/noi", method = RequestMethod.GET)
String noi() { ... }

// la fel, mai scurt:
@GetMapping("/noi")
String noi() { ... }

Vei întâlni forma lungă în proiecte mai vechi. Pentru cod nou, folosește @RequestMapping pe clasă (prefixul) și @GetMapping, @PostMapping etc. pe metode.

Greșeli frecvente

  • Repeți prefixul și pe metodă: cu @RequestMapping("/api/produse") pe clasă și @GetMapping("/api/produse/noi") pe metodă, ruta devine /api/produse/api/produse/noi.
  • **Pui @RequestMapping doar pe clasă, fără @GetMapping pe metode**: metodele nu devin rute.
  • **Uiți @RestController**: prefixul singur nu face din clasă un controller.
  • Schimbi prefixul fără să anunți clienții: orice schimbare a adreselor strică aplicațiile care le folosesc; de aceea există versiunile.

Pe scurt

  • @RequestMapping("/prefix") pe clasă se adaugă în fața tuturor rutelor din clasă.
  • @GetMapping fără argument = chiar prefixul.
  • API-urile reale încep des cu /api și cu o versiune: /api/v1/....
  • Pe metode folosește @GetMapping, @PostMapping etc. (forma scurtă a lui @RequestMapping).
Exercițiul tău

Mută toate rutele magazinului sub prefixul /api/magazin: GET /api/magazin întoarce deschis, GET /api/magazin/orar întoarce 9-18, iar GET /api/magazin/contact întoarce contact@magazin.ro. Laboratorul trimite și GET /orar, care trebuie să primească 404.

  • Pune @RequestMapping("/api/magazin") pe clasa MagazinController.
  • Adaugă o metodă cu @GetMapping fără argument care întoarce deschis.
  • Adaugă @GetMapping("/orar") și @GetMapping("/contact"), fără să repeți prefixul.
Prefixul se scrie o singură dată, pe clasă; pe metode scrii doar ce vine după el.

Soluția exercițiului

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

@RestController
@RequestMapping("/api/magazin")
class MagazinController {
    @GetMapping
    String stare() {
        return "deschis";
    }

    @GetMapping("/orar")
    String orar() {
        return "9-18";
    }

    @GetMapping("/contact")
    String contact() {
        return "contact@magazin.ro";
    }
}
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 5 · Prefixul comun cu @RequestMapping
Progres 0% 0 din 20
Lecția curentă 5 / 18 Rute