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

Liste și dicționare în JSON

Un API întoarce rar un singur obiect: lista produselor, istoricul comenzilor, statistici. În lecția aceasta vezi cum devin List un tablou JSON și Map un obiect JSON, de ce contează ordinea cheilor și cum pui obiecte unele în altele.

List devine tablou JSON

În JSON, un tablou se scrie între paranteze drepte: [1, 2, 3]. Când metoda întoarce un List, Jackson scrie fiecare element, în ordine, între [ și ]. Elementele pot fi obiecte (record-uri) sau valori simple.

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

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

record Curs(String titlu, int lectii) { }

@RestController
class CursController {
    @GetMapping("/cursuri")
    List<Curs> cursuri() {
        return List.of(
            new Curs("Java", 300),
            new Curs("Spring Boot", 120),
            new Curs("SQL", 150)
        );
    }

    @GetMapping("/cursuri/titluri")
    List<String> titluri() {
        return List.of("Java", "Spring Boot", "SQL");
    }
}

// > GET /cursuri
// > GET /cursuri/titluri
Tomcat started on port 8080 (http)
Started Application
GET /cursuri → 200
[{"titlu":"Java","lectii":300},{"titlu":"Spring Boot","lectii":120},{"titlu":"SQL","lectii":150}]
GET /cursuri/titluri → 200
["Java","Spring Boot","SQL"]

List.of(...) creează o listă fixă, numai pentru citit. Este potrivită pentru date care nu se schimbă; în lecția 10 folosești ArrayList, la care poți adăuga elemente.

Map devine obiect JSON

Un Map<String, Object> devine un obiect JSON: fiecare cheie devine un câmp. Este util când răspunsul este mic și nu merită un record (de exemplu niște statistici). Atenție însă la ordine:

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

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

@RestController
class StareController {
    @GetMapping("/stare")
    Map<String, Object> stare() {
        return Map.of("versiune", "1.0", "utilizatori", 1250, "activ", true);
    }

    @GetMapping("/stare/ordonat")
    Map<String, Object> stareOrdonat() {
        Map<String, Object> m = new LinkedHashMap<>();
        m.put("versiune", "1.0");
        m.put("utilizatori", 1250);
        m.put("activ", true);
        return m;
    }
}

// > GET /stare
// > GET /stare/ordonat
Tomcat started on port 8080 (http)
Started Application
GET /stare → 200
{"activ":true,"utilizatori":1250,"versiune":"1.0"}
GET /stare/ordonat → 200
{"versiune":"1.0","utilizatori":1250,"activ":true}
  • Map.of(...) nu garantează ordinea cheilor. În Spring real ordinea poate fi oricare și se poate schimba de la o rulare la alta. Laboratorul afișează cheile sortate alfabetic, ca rezultatul să fie mereu același.
  • LinkedHashMap păstrează ordinea în care ai pus cheile (put). Folosește-l când ordinea contează pentru cine citește răspunsul.
  • TreeMap ține cheile sortate alfabetic.
Record sau Map?

Pentru date cu structură stabilă (un produs, un client), preferă un record: are tipuri, iar compilatorul te ajută. Un Map e bun pentru răspunsuri mici și ocazionale. În proiectele mari, aproape tot ce iese din API este record (sau DTO, lecția 21).

Obiecte imbricate și liste în obiecte

Un record poate conține alt record sau o listă. Jackson scrie totul recursiv: obiectul din obiect devine {...} în interior, lista devine [...]. Lista poate sta într-un câmp al controller-ului, ca mai multe rute să o folosească:

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

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

record Adresa(String oras, String strada) { }
record Client(String nume, Adresa adresa, List<String> telefoane) { }

@RestController
class ClientController {
    private final List<Client> clienti = List.of(
        new Client("Ana", new Adresa("Cluj-Napoca", "Memorandumului 5"), List.of("0722000111")),
        new Client("Mihai", new Adresa("Iași", "Lăpușneanu 12"), List.of())
    );

    @GetMapping("/clienti")
    List<Client> toti() {
        return clienti;
    }

    @GetMapping("/clienti/numar")
    int numar() {
        return clienti.size();
    }
}

// > GET /clienti
// > GET /clienti/numar
Tomcat started on port 8080 (http)
Started Application
GET /clienti → 200
[{"nume":"Ana","adresa":{"oras":"Cluj-Napoca","strada":"Memorandumului 5"},"telefoane":["0722000111"]},{"nume":"Mihai","adresa":{"oras":"Iași","strada":"Lăpușneanu 12"},"telefoane":[]}]
GET /clienti/numar → 200
2

Mihai nu are telefoane, deci telefoane este un tablou gol [], nu null. Ruta /clienti/numar întoarce un int, care se trimite ca număr simplu.

Exemple reale

RăspunsForma JSON
lista de produse dintr-o categorietablou de obiecte [{...}, {...}]
comanda cu produsele eiobiect cu un tablou în el: {"id":7, "produse":[...]}
profilul cu adresaobiect în obiect: {"nume":"Ana", "adresa":{...}}
statistici pe pagina de adminobiect simplu: {"comenzi":120, "incasari":15400.5}

Greșeli frecvente

  • **Te bazezi pe ordinea din Map.of sau HashMap**: în producție poate ieși altfel. Folosește LinkedHashMap sau un record.
  • **Modifici o listă List.of**: add aruncă UnsupportedOperationException. Pentru liste care se schimbă folosește new ArrayList<>().
  • **Întorci null în loc de listă goală**: clientul trebuie să verifice null; o listă goală [] este mai ușor de folosit.
  • **Pui Map peste tot**: pierzi tipurile și verificarea compilatorului; pentru date stabile folosește record-uri.

Pe scurt

  • List<T> → tablou JSON [...], în ordinea elementelor.
  • Map<String, Object> → obiect JSON; ordinea din Map.of/HashMap nu e garantată, LinkedHashMap păstrează ordinea inserării.
  • Record-uri în record-uri și liste în record-uri devin JSON imbricat.
  • Lista poate sta într-un câmp al controller-ului, folosit de mai multe rute.
Exercițiul tău

Controller-ul are deja lista a trei produse. Adaugă două rute: GET /produse întoarce toată lista (tablou JSON), iar GET /statistici întoarce un obiect cu numar (câte produse sunt) și total (suma prețurilor), în această ordine, construit cu LinkedHashMap. Calculează valorile din listă, nu le scrie fix.

  • Adaugă @GetMapping("/produse") care întoarce List<Produs> (câmpul produse).
  • Adaugă @GetMapping("/statistici") care întoarce Map<String, Object>.
  • Calculează totalul cu o buclă for peste produse (sau cu un stream).
  • Pune în LinkedHashMap întâi numar (produse.size()), apoi total.
Map<String, Object> m = new LinkedHashMap<>(); m.put("numar", produse.size()); m.put("total", total); return m;

Soluția exercițiului

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

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

record Produs(long id, String nume, double pret) { }

@RestController
class ProdusController {
    private final List<Produs> produse = List.of(
        new Produs(1, "Laptop", 3500.0),
        new Produs(2, "Mouse", 99.5),
        new Produs(3, "Monitor", 899.0)
    );

    @GetMapping("/produse")
    List<Produs> toate() {
        return produse;
    }

    @GetMapping("/statistici")
    Map<String, Object> statistici() {
        double total = 0;
        for (Produs p : produse) {
            total += p.pret();
        }
        Map<String, Object> rezultat = new LinkedHashMap<>();
        rezultat.put("numar", produse.size());
        rezultat.put("total", total);
        return rezultat;
    }
}
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 9 · Liste și dicționare în JSON
Progres 0% 0 din 20
Lecția curentă 9 / 18 Json