Kurs NestJS · Moduł 1: Podstawy NestJS
Pierwsze REST API - operacje CRUD
W tej lekcji9
Ave, budowniczy dróg! Konsul Caesar.js powierza Ci teraz jedno z najważniejszych zadań w imperium - budowę systemu dróg REST API. Tak jak rzymskie drogi łączyły wszystkie prowincje imperium, tak REST API łączy naszą aplikację serwerową ze światem zewnętrznym. Czas nauczyć się operacji CRUD - fundamentu każdego REST API!
Czym jest CRUD?
CRUD to akronim od czterech podstawowych operacji na danych:
- Create (Tworzenie) - rekrutacja nowych legionistów
- Read (Odczyt) - przeglądanie rejestrów imperium
- Update (Aktualizacja) - awansowanie legionistów
- Delete (Usuwanie) - wykreślanie z rejestrów
Każda operacja CRUD odpowiada konkretnej metodzie HTTP i dekoratorowi w NestJS:
| Operacja | Metoda HTTP | Dekorator NestJS |
|---|---|---|
| Create | POST | @Post() |
| Read | GET | @Get() |
| Update | PUT / PATCH | @Put() / @Patch() |
| Delete | DELETE | @Delete() |
Budujemy kontroler CRUD krok po kroku
Zbudujmy kompletny kontroler do zarządzania legionistami naszego imperium:
import {
Controller, Get, Post, Put, Delete, Patch,
Param, Body, Query, HttpCode, HttpStatus, NotFoundException
} from '@nestjs/common';
// Interfejs legionisty
interface Legionary {
id: number;
name: string;
rank: string;
province: string;
}
@Controller('legionaries')
export class LegionariesController {
// Tymczasowa tablica jako "baza danych"
private legionaries: Legionary[] = [
{ id: 1, name: 'Marcus Aurelius', rank: 'Centurio', province: 'Roma' },
{ id: 2, name: 'Gaius Julius', rank: 'Miles', province: 'Gallia' },
];
// Następny wolny numer (1 i 2 są zajęte)
private nextId = 3;
}READ - odczyt danych (@Get)
Dekorator @Get() obsługuje żądania HTTP GET. Używamy go do pobierania danych:
@Controller('legionaries')
export class LegionariesController {
// GET /legionaries - pobierz wszystkich legionistów
@Get()
findAll(): Legionary[] {
return this.legionaries;
}
// GET /legionaries/search?province=Roma - filtrowanie po prowincji
@Get('search')
findByProvince(@Query('province') province: string): Legionary[] {
return this.legionaries.filter(l => l.province === province);
}
// GET /legionaries/1 - pobierz jednego po ID
@Get(':id')
findOne(@Param('id') id: string): Legionary {
const legionary = this.legionaries.find(l => l.id === Number(id));
if (!legionary) {
throw new NotFoundException('Legionista nie znaleziony!');
}
return legionary;
}
}Zauważ trzy kluczowe dekoratory parametrów:
@Param('id')- wyciąga parametr z URL (np./legionaries/1)@Query('province')- wyciąga parametr zapytania (np.?province=Roma)@Body()- wyciąga dane z ciała żądania (dla POST/PUT)
Dwie rzeczy w tym kodzie są celowe. Trasa search stoi przed :id - inaczej GET /legionaries/search trafiłoby do findOne z id równym 'search'. A brak legionisty zgłaszamy wyjątkiem NotFoundException z @nestjs/common: NestJS odpowie wtedy kodem 404 Not Found. Zwykły throw new Error(...) dałby klientowi 500 Internal Server Error, jakby zepsuł się serwer.
CREATE - tworzenie danych (@Post)
Dekorator @Post() obsługuje żądania HTTP POST. Służy do tworzenia nowych zasobów:
// POST /legionaries - rekrutacja nowego legionisty
@Post()
@HttpCode(HttpStatus.CREATED) // Zwraca status 201
create(@Body() newLegionary: { name: string; rank: string; province: string }): Legionary {
const legionary: Legionary = {
id: this.nextId++,
...newLegionary,
};
this.legionaries.push(legionary);
return legionary;
}Dekorator @Body() wyciąga dane z ciała żądania JSON. Dekorator @HttpCode() pozwala ustawić kod odpowiedzi HTTP - dla tworzenia zasobów standardem jest 201 Created.
Numer nowego legionisty nadaje licznik nextId z klasy kontrolera. Rośnie przy każdej rekrutacji, więc nie powtórzy się nawet po wykreśleniu kogoś z tablicy - numer liczony jako length + 1 mógłby już należeć do innego legionisty.
UPDATE - aktualizacja danych (@Put i @Patch)
Mamy dwa dekoratory do aktualizacji:
@Put()- zastępuje cały zasób (pełna aktualizacja)@Patch()- aktualizuje tylko wybrane pola (częściowa aktualizacja)
// PUT /legionaries/1 - pełna aktualizacja legionisty
@Put(':id')
update(
@Param('id') id: string,
@Body() updateData: { name: string; rank: string; province: string },
): Legionary {
const index = this.legionaries.findIndex(l => l.id === Number(id));
if (index === -1) {
throw new NotFoundException('Legionista nie znaleziony!');
}
this.legionaries[index] = { id: Number(id), ...updateData };
return this.legionaries[index];
}
// PATCH /legionaries/1 - częściowa aktualizacja (np. tylko ranga)
@Patch(':id')
partialUpdate(
@Param('id') id: string,
@Body() updateData: Partial<Legionary>,
): Legionary {
const index = this.legionaries.findIndex(l => l.id === Number(id));
if (index === -1) {
throw new NotFoundException('Legionista nie znaleziony!');
}
this.legionaries[index] = { ...this.legionaries[index], ...updateData };
return this.legionaries[index];
}DELETE - usuwanie danych (@Delete)
Dekorator @Delete() obsługuje żądania HTTP DELETE:
// DELETE /legionaries/1 - wykreślenie legionisty
@Delete(':id')
@HttpCode(HttpStatus.NO_CONTENT) // Zwraca status 204
remove(@Param('id') id: string): void {
const index = this.legionaries.findIndex(l => l.id === Number(id));
if (index === -1) {
throw new NotFoundException('Legionista nie znaleziony!');
}
this.legionaries.splice(index, 1);
}Dla operacji usuwania standardowy kod odpowiedzi to 204 No Content - oznacza sukces bez zwracania danych.
Kody statusów HTTP
Znajomość kodów HTTP to obowiązek każdego budowniczego API:
| Kod | Nazwa | Kiedy używać |
|---|---|---|
| 200 | OK | Sukces (domyślny dla GET, PUT, PATCH) |
| 201 | Created | Nowy zasób został stworzony (POST) |
| 204 | No Content | Sukces bez treści odpowiedzi (DELETE) |
| 400 | Bad Request | Nieprawidłowe dane wejściowe |
| 404 | Not Found | Zasób nie istnieje |
| 500 | Internal Server Error | Błąd serwera |
Kontroler + Serwis - prawidłowy wzorzec
W prawdziwym imperium kontroler nie wykonuje logiki sam - deleguje ją do serwisu:
// legionaries.service.ts
@Injectable()
export class LegionariesService {
private legionaries: Legionary[] = [];
private nextId = 1;
findAll(): Legionary[] {
return this.legionaries;
}
findOne(id: number): Legionary {
return this.legionaries.find(l => l.id === id);
}
create(data: { name: string; rank: string; province: string }): Legionary {
const legionary = { id: this.nextId++, ...data };
this.legionaries.push(legionary);
return legionary;
}
update(id: number, data: Partial<Legionary>): Legionary {
const index = this.legionaries.findIndex(l => l.id === id);
this.legionaries[index] = { ...this.legionaries[index], ...data };
return this.legionaries[index];
}
remove(id: number): void {
this.legionaries = this.legionaries.filter(l => l.id !== id);
}
}
// legionaries.controller.ts
@Controller('legionaries')
export class LegionariesController {
constructor(private readonly legionariesService: LegionariesService) {}
@Get()
findAll() {
return this.legionariesService.findAll();
}
@Post()
create(@Body() data: { name: string; rank: string; province: string }) {
return this.legionariesService.create(data);
}
}Testowanie z curl
Możesz przetestować swoje API używając narzędzia curl w terminalu:
# GET - pobierz wszystkich
curl http://localhost:3000/legionaries
# POST - stwórz nowego
curl -X POST http://localhost:3000/legionaries \
-H "Content-Type: application/json" \
-d '{"name": "Titus Flavius", "rank": "Miles", "province": "Judea"}'
# PUT - pełna aktualizacja
curl -X PUT http://localhost:3000/legionaries/1 \
-H "Content-Type: application/json" \
-d '{"name": "Marcus Aurelius", "rank": "Legatus", "province": "Roma"}'
# DELETE - usunięcie
curl -X DELETE http://localhost:3000/legionaries/1Brawo, budowniczy! Teraz znasz fundamenty REST API - drogi, które łączą wszystkie prowincje naszego imperium NestJS!
Kod do tej lekcji: src/crud-controller.ts
// Pierwsze REST API - Operacje CRUD w Imperium
import {
Controller, Get, Post, Put, Delete, Patch,
Param, Body, Query, HttpCode, HttpStatus, Injectable
} from '@nestjs/common';
console.log("REST API CRUD - drogi imperium!");
// ===========================================
// 1. Interfejs i dane
// ===========================================
interface Legionary {
id: number;
name: string;
rank: string;
province: string;
}
const legionaries: Legionary[] = [
{ id: 1, name: 'Marcus Aurelius', rank: 'Centurio', province: 'Roma' },
{ id: 2, name: 'Gaius Julius', rank: 'Miles', province: 'Gallia' },
{ id: 3, name: 'Titus Flavius', rank: 'Optio', province: 'Judea' },
];
// ===========================================
// 2. READ - @Get() - pobieranie danych
// ===========================================
// GET /legionaries - lista wszystkich
// @Get()
function findAll(): Legionary[] {
return legionaries;
}
// GET /legionaries/:id - jeden po ID
// @Get(':id')
function findOne(id: string): Legionary | undefined {
return legionaries.find(l => l.id === Number(id));
}
// GET /legionaries?province=Roma - filtrowanie
// @Get('search')
function findByProvince(province: string): Legionary[] {
return legionaries.filter(l => l.province === province);
}
console.log("GET /legionaries:", findAll());
console.log("GET /legionaries/1:", findOne('1'));
console.log("GET ?province=Roma:", findByProvince('Roma'));
// ===========================================
// 3. CREATE - @Post() - tworzenie danych
// ===========================================
// POST /legionaries
function create(data: { name: string; rank: string; province: string }): Legionary {
const newLegionary: Legionary = {
id: legionaries.length + 1,
...data,
};
legionaries.push(newLegionary);
return newLegionary;
}
const created = create({ name: 'Lucius Verus', rank: 'Miles', province: 'Syria' });
console.log("\nPOST - nowy legionista:", created);
// ===========================================
// 4. UPDATE - @Put() / @Patch()
// ===========================================
// PUT /legionaries/:id - pełna aktualizacja
function update(id: string, data: Omit<Legionary, 'id'>): Legionary | null {
const index = legionaries.findIndex(l => l.id === Number(id));
if (index === -1) return null;
legionaries[index] = { id: Number(id), ...data };
return legionaries[index];
}
// PATCH /legionaries/:id - częściowa aktualizacja
function partialUpdate(id: string, data: Partial<Legionary>): Legionary | null {
const index = legionaries.findIndex(l => l.id === Number(id));
if (index === -1) return null;
legionaries[index] = { ...legionaries[index], ...data };
return legionaries[index];
}
console.log("\nPUT /legionaries/2:", update('2', { name: 'Gaius Julius', rank: 'Centurio', province: 'Roma' }));
console.log("PATCH /legionaries/3:", partialUpdate('3', { rank: 'Centurio' }));
// ===========================================
// 5. DELETE - @Delete() - usuwanie danych
// ===========================================
function remove(id: string): boolean {
const index = legionaries.findIndex(l => l.id === Number(id));
if (index === -1) return false;
legionaries.splice(index, 1);
return true;
}
console.log("\nDELETE /legionaries/4:", remove('4'));
console.log("Stan po operacjach:", legionaries);
// ===========================================
// 6. Kody statusów HTTP
// ===========================================
console.log("\n=== KODY STATUSÓW HTTP ===");
console.log("200 OK - sukces (GET, PUT, PATCH)");
console.log("201 Created - zasób stworzony (POST)");
console.log("204 No Content - sukces bez treści (DELETE)");
console.log("400 Bad Request - nieprawidłowe dane");
console.log("404 Not Found - zasób nie istnieje");
console.log("\n=== DEKORATORY CRUD ===");
console.log("@Get() -> odczyt danych");
console.log("@Post() -> tworzenie danych");
console.log("@Put() -> pełna aktualizacja");
console.log("@Patch() -> częściowa aktualizacja");
console.log("@Delete() -> usuwanie danych");
console.log("@Param() -> parametr z URL");
console.log("@Body() -> dane z ciała żądania");
console.log("@Query() -> parametr zapytania");
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Co oznacza akronim CRUD?
2. Jaki kod odpowiedzi NestJS zwraca domyślnie z metody oznaczonej dekoratorem @Post()?
3. Do czego służy dekorator @Param() w kontrolerze NestJS?
Zadania praktyczne w grze
- Edytor kodu
W kontrolerze LegionController z dekoratorem @Controller('legionaries') trzymaj tablicę legionistów, np. [{ id: 1, name: 'Marcus Aurelius' }]. Napisz metodę findOne z @Get(':id'), która odczytuje id przez @Param('id') i zwraca legionistę o tym id, a gdy go nie ma, rzuca NotFoundException. Pamiętaj, że id z adresu jest tekstem.
- Układanie w poziomie
Ułóż elementy metody POST w kontrolerze NestJS:
- Układanie w pionie
Uporządkuj kody statusów HTTP od sukcesu do błędu serwera:
- Edytor kodu
W kontrolerze LegionController z dekoratorem @Controller('legionaries') i tablicą legionistów napisz metodę remove z @Delete(':id') i @HttpCode(HttpStatus.NO_CONTENT), która odczytuje id przez @Param('id') i usuwa legionistę o tym id z tablicy. Metoda nic nie zwraca.