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:
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ța | Ruta | Răspuns |
|---|---|---|
| toate sarcinile | GET /sarcini | 200 + listă |
| doar cele terminate / neterminate | GET /sarcini?gata=true / ?gata=false | 200 + listă filtrată |
| adaugă o sarcină | POST /sarcini | 201 + Location + sarcina (cu gata = false) |
| marchează ca terminată | PATCH /sarcini/{id}/gata | 200 + sarcina sau 404 |
| rezumat | GET /sarcini/statistici | 200 + {"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 /bileteTomcat 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}]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
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.
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ă.
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);
}
} 