...
← Curs Spring Boot și REST API: toate lecțiile
Lecția 17 · Mini-proiect

Mini-proiect: API pentru lista de sarcini

E timpul pentru primul tău proiect complet. Primești un „tichet” ca la serviciu: un API pentru o listă de sarcini, cu filtrare, o acțiune de marcare ca terminată și statistici. Îl rezolvi pas cu pas, cum lucrează un programator într-o echipă: cerințe, rute, cod, test.

Tichetul

În echipele reale, munca vine sub forma unor tichete (în Jira, Azure DevOps, GitHub Issues). Al tău arată așa:

TASK-142: API pentru lista de sarcini

Echipa de mobil are nevoie de un API pentru sarcini. O sarcină are id, titlu, gata (terminată sau nu) și prioritate (1 = mare, 2 = medie, 3 = mică). Aplicația trebuie să poată: afișa toate sarcinile sau doar pe cele terminate/neterminate, adăuga o sarcină (nouă = neterminată), marca o sarcină ca terminată și afișa un rezumat (câte sunt în total și câte sunt terminate).

Înainte să scrii cod, citește tichetul și întreabă-te: ce resurse am, ce operații se cer, ce se întâmplă când ceva lipsește?

De la cerințe la rute

Fiecare cerință devine o rută. Scrie tabelul ăsta înainte de cod: este contractul cu echipa de mobil.

CerințaRutaRăspuns
toate sarcinileGET /sarcini200 + listă
doar cele terminate / neterminateGET /sarcini?gata=true / ?gata=false200 + listă filtrată
adaugă o sarcinăPOST /sarcini201 + Location + sarcina (cu gata = false)
marchează ca terminatăPATCH /sarcini/{id}/gata200 + sarcina sau 404
rezumatGET /sarcini/statistici200 + {"total":..., "terminate":...}
  • Filtrul este un parametru de interogare opțional, nu o rută separată: filtrează aceeași colecție (lecția 7).
  • Marcarea este o modificare parțială (doar câmpul gata), deci PATCH. Calea /sarcini/{id}/gata descrie exact ce se schimbă și nu are nevoie de corp.
  • Statisticile au o structură fixă, deci un record Statistici, nu un Map.

Bucățile noi: filtru opțional și acțiune PATCH

Aproape totul îl știi deja. Două tipare sunt noi în combinația asta: un filtru Boolean opțional (null = fără filtru) și un PATCH care modifică un singur câmp al unui record. Iată-le pe un sistem de bilete de suport:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;
import java.net.URI;
import java.util.*;

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

record Bilet(long id, String titlu, boolean rezolvat) { }

@RestController
@RequestMapping("/bilete")
class BiletController {
    private final List<Bilet> bilete = new ArrayList<>(List.of(
        new Bilet(1, "Nu merge plata", false),
        new Bilet(2, "Parola uitată", true),
        new Bilet(3, "Factura lipsă", false)
    ));

    @GetMapping
    List<Bilet> lista(@RequestParam(required = false) Boolean rezolvat) {
        if (rezolvat == null) {
            return bilete;
        }
        return bilete.stream().filter(b -> b.rezolvat() == rezolvat).toList();
    }

    @PatchMapping("/{id}/rezolvat")
    ResponseEntity<Bilet> rezolva(@PathVariable long id) {
        for (int i = 0; i < bilete.size(); i++) {
            Bilet b = bilete.get(i);
            if (b.id() == id) {
                Bilet nou = new Bilet(b.id(), b.titlu(), true);
                bilete.set(i, nou);
                return ResponseEntity.ok(nou);
            }
        }
        return ResponseEntity.notFound().build();
    }
}

// > GET /bilete?rezolvat=false
// > PATCH /bilete/1/rezolvat
// > GET /bilete?rezolvat=false
// > GET /bilete
Tomcat started on port 8080 (http)
Started Application
GET /bilete?rezolvat=false → 200
[{"id":1,"titlu":"Nu merge plata","rezolvat":false},{"id":3,"titlu":"Factura lipsă","rezolvat":false}]
PATCH /bilete/1/rezolvat → 200
{"id":1,"titlu":"Nu merge plata","rezolvat":true}
GET /bilete?rezolvat=false → 200
[{"id":3,"titlu":"Factura lipsă","rezolvat":false}]
GET /bilete → 200
[{"id":1,"titlu":"Nu merge plata","rezolvat":true},{"id":2,"titlu":"Parola uitată","rezolvat":true},{"id":3,"titlu":"Factura lipsă","rezolvat":false}]
1
@RequestParam(required = false) Boolean rezolvat este null când parametrul lipsește, deci întorci toată lista.
2
Altfel, stream().filter(...).toList() păstrează doar biletele cu valoarea cerută.
3
Record-urile nu se pot modifica, așa că PATCH construiește un bilet nou, cu aceleași date și rezolvat = true, și îl pune în listă în locul celui vechi.
Boolean, nu boolean

Cu boolean (tip primitiv), un parametru lipsă nu poate fi null, iar Spring răspunde cu 400. Boolean (clasa) permite null, adică „clientul nu a cerut filtrare”.

Planul de lucru

1
Modelul: record-urile Sarcina și Statistici (sunt deja în starter).
2
Citirea: GET /sarcini cu filtrul opțional gata. Testează mental cu ?gata=true, ?gata=false și fără parametru.
3
Crearea: POST /sarcini cu 201 și Location. Sarcina nouă are mereu gata = false, orice ar trimite clientul.
4
Acțiunea: PATCH /sarcini/{id}/gata, cu 404 pentru id-uri inexistente.
5
Rezumatul: GET /sarcini/statistici, numărând sarcinile cu gata.
6
Testul: rulează scenariul și compară fiecare răspuns cu tabelul de rute.

Lucrează pe rând, câte o rută, și rulează după fiecare. Poți adăuga propriile cereri la final, de exemplu // > GET /sarcini?gata=true.

Ce verifică un coleg la code review

  • Codurile de status sunt cele din tabel (201 la creare, 404 pentru id inexistent)?
  • Clientul poate trimite "gata": true sau un id la creare? Nu ar trebui să conteze.
  • Statisticile se calculează din listă (după POST și PATCH se schimbă), nu sunt scrise fix?
  • Rutele sunt substantive, fără verbe în adresă (/sarcini/3/gata, nu /marcheazaGata/3)?

Pe scurt

  • Un tichet se transformă întâi într-un tabel de rute: cerință → metodă + cale → răspuns.
  • Filtrele sunt parametri de interogare opționali (Boolean cu required = false).
  • O acțiune care schimbă un câmp este un PATCH pe o cale descriptivă (/{id}/gata).
  • Record-urile se „modifică” construind unul nou și înlocuindu-l în listă.
  • Verifici totul cu un scenariu de cereri, ca un tester.
Exercițiul tău

Rezolvă tichetul TASK-142. Starter-ul are record-urile și trei sarcini (prima este deja terminată). Implementează cele patru rute din tabelul lecției: GET /sarcini cu filtrul opțional gata, POST /sarcini (201, Location, sarcina nouă neterminată), PATCH /sarcini/{id}/gata (200 sau 404) și GET /sarcini/statistici. Laboratorul rulează un scenariu de 8 cereri și afișează antetul Location.

  • GET /sarcini: primește @RequestParam(required = false) Boolean gata; fără el întoarce toată lista, altfel filtrează.
  • POST /sarcini: id-ul următor (de la 4), gata = false, titlul și prioritatea din corp; răspuns 201 cu Location: /sarcini/{id}.
  • PATCH /sarcini/{id}/gata: înlocuiește sarcina cu una identică, dar cu gata = true; 404 dacă id-ul nu există.
  • GET /sarcini/statistici: întoarce new Statistici(total, terminate), calculat din listă.
Exemplul cu biletele de suport din lecție are exact tiparele pentru filtru și pentru PATCH; POST cu 201 este cel din lecțiile 13 și 16.

Soluția exercițiului

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;
import java.net.URI;
import java.util.*;

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

record Sarcina(long id, String titlu, boolean gata, int prioritate) { }
record Statistici(int total, int terminate) { }

@RestController
@RequestMapping("/sarcini")
class SarcinaController {
    private final List<Sarcina> sarcini = new ArrayList<>(List.of(
        new Sarcina(1, "Configurează proiectul", true, 1),
        new Sarcina(2, "Scrie rutele", false, 1),
        new Sarcina(3, "Testează cu cereri", false, 2)
    ));
    private long ultimulId = 3;

    @GetMapping
    List<Sarcina> lista(@RequestParam(required = false) Boolean gata) {
        if (gata == null) {
            return sarcini;
        }
        return sarcini.stream().filter(s -> s.gata() == gata).toList();
    }

    @PostMapping
    ResponseEntity<Sarcina> adauga(@RequestBody Sarcina primita) {
        ultimulId++;
        Sarcina sarcina = new Sarcina(ultimulId, primita.titlu(), false, primita.prioritate());
        sarcini.add(sarcina);
        return ResponseEntity.created(URI.create("/sarcini/" + sarcina.id())).body(sarcina);
    }

    @PatchMapping("/{id}/gata")
    ResponseEntity<Sarcina> marcheaza(@PathVariable long id) {
        for (int i = 0; i < sarcini.size(); i++) {
            Sarcina s = sarcini.get(i);
            if (s.id() == id) {
                Sarcina terminata = new Sarcina(s.id(), s.titlu(), true, s.prioritate());
                sarcini.set(i, terminata);
                return ResponseEntity.ok(terminata);
            }
        }
        return ResponseEntity.notFound().build();
    }

    @GetMapping("/statistici")
    Statistici statistici() {
        int terminate = 0;
        for (Sarcina s : sarcini) {
            if (s.gata()) {
                terminate++;
            }
        }
        return new Statistici(sarcini.size(), terminate);
    }
}
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 17 · Mini-proiect: API pentru lista de sarcini
Progres 0% 0 din 20
Lecția curentă 17 / 18 Mini-proiect