Kurs NestJS · Moduł 1: Podstawy NestJS
Kontrolery - centurionowie Imperium
W tej lekcji5
Do bramy obozu przybywa posłaniec z żądaniem: GET /legion/5. Serwer je odebrał - ale kto ma je obsłużyć? Aplikacja ma kilkadziesiąt metod i żadna nie wie, że to właśnie do niej.
W legionie od rozdzielania rozkazów jest centurion. Stoi między posłańcem a żołnierzami: przyjmuje rozkaz, rozpoznaje, kogo dotyczy, przekazuje dalej i odsyła odpowiedź. Sam nie wykonuje pracy - on ją kieruje. W NestJS tym centurionem jest kontroler.
Deklaracja kontrolera
Kontroler to klasa z dekoratorem wskazującym, jakim odcinkiem tras się zajmuje:
@Controller('legion')
export class LegionController { }Kolejność jest zawsze ta sama: @Controller('legion'), potem export class, na końcu nazwa klasy z ciałem.
Argument 'legion' to prefiks trasy. Wszystkie metody tej klasy będą obsługiwać adresy zaczynające się od /legion - i nie musisz tego powtarzać przy każdej z nich. Kontroler bez argumentu, @Controller(), przejmuje trasy od korzenia.
Cztery czasowniki
Wewnątrz kontrolera każda metoda dostaje dekorator mówiący, na jakie żądanie odpowiada:
@Controller('tributes')
export class TributesController {
@Get()
findAll() { }
@Post()
create() { }
@Put(':id')
update() { }
@Delete(':id')
remove() { }
}Cztery dekoratory odpowiadają czterem czynnościom na zasobie. @Get() pobiera, @Post() tworzy nowy zasób, @Put() aktualizuje istniejący, @Delete() usuwa.
Rozróżnienie @Post od @Put bywa mylące, więc zapamiętaj je po skutku powtórzenia: wysłanie tego samego @Post dwa razy utworzy dwa zasoby, a tego samego @Put - zostawi jeden, po prostu zapisany dwukrotnie.
Argument dekoratora dokłada kawałek trasy. @Put(':id') w kontrolerze z prefiksem tributes obsłuży adres /tributes/42. Dwukropek oznacza parametr - miejsce, w które wpada dowolna wartość.
Trzy miejsca, z których biorą się dane
Skoro trasa może zawierać parametr, trzeba go jakoś odczytać. Dane przychodzą w żądaniu trzema drogami i każda ma swój dekorator:
@Get('search')
search(@Query('province') province: string) { }
@Get(':id')
findOne(@Param('id') id: string) { }
@Post()
create(@Body() dto: CreateTributeDto) { }@Param('id') wyciąga wartość ze ścieżki adresu - to on odczyta 5 z /legion/5. @Query('province') bierze parametr zapytania, czyli to, co stoi po znaku zapytania: ?province=rome. @Body() sięga po ciało żądania, wysyłane przy @Post i @Put.
Zwróć uwagę na kolejność dwóch pierwszych metod. NestJS dopasowuje trasy w kolejności deklaracji, a :id pasuje do każdego tekstu - także do słowa search. Gdyby findOne stało wyżej, żądanie GET /legion/search trafiłoby do niego z id równym 'search'. Dlatego trasy ze stałym fragmentem deklarujemy przed trasami z parametrem.
Te trzy pokrywają wszystko, czego zwykle potrzebujesz. Uwaga na dwie nazwy, które brzmią prawdopodobnie: @Path() w NestJS nie istnieje - do ścieżki służy @Param. @Header() istnieje, ale robi coś innego: ustawia nagłówek odpowiedzi. Do czytania nagłówków żądania służy @Headers(), w liczbie mnogiej.
Metoda kontrolera od środka
Złóżmy to w całość. Kolejność elementów metody jest niezmienna:
@Get()
getAllLegionaries() {
return this.service.findAll();
}Najpierw dekorator @Get(), potem nazwa metody, dalej ciało w nawiasach klamrowych, a w nim return this.service.findAll().
I tu widać, czym kontroler naprawdę jest. Ta metoda nie zawiera logiki - przyjmuje żądanie i przekazuje je serwisowi. Centurion nie kuje mieczy; wie, do którego kowala posłać.
To jest reguła, którą polecam trzymać od pierwszego dnia: w kontrolerze nie ma zapytań do bazy, obliczeń ani reguł biznesowych. Gdy metoda kontrolera rośnie ponad kilka linii, to znak, że robi coś, co należy do serwisu. Zysk jest praktyczny - tę samą logikę wywołasz potem z zadania wsadowego albo konsumenta kolejki, gdzie żadnego HTTP nie ma.
Kontroler nie jest też pierwszym przystankiem żądania. Po drodze stoją warstwy, które poznasz w kolejnych modułach: najpierw middleware, potem guardy (straże, które decydują, czy wpuścić żądanie), dalej interceptory (przed wywołaniem metody) i pipe'y (sprawdzają i zamieniają dane, np. ValidationPipe). Dopiero wtedy działa metoda kontrolera, a jej wynik wraca do klienta przez interceptory.
Zwróć uwagę, że nie budujemy odpowiedzi ręcznie. Zwrócona wartość zostanie zamieniona na JSON, a kod odpowiedzi NestJS dobierze sam: 200 dla większości metod, 201 dla @Post, bo coś powstało.
Podsumowanie
Centurion stoi u bramy i wie, komu przekazać rozkaz:
- kontroler przyjmuje żądanie i kieruje je dalej - sam nie wykonuje pracy,
- deklaracja w kolejności:
@Controller('prefiks'),export class, nazwa klasy, - argument
@Controllerto prefiks trasy wspólny dla wszystkich metod klasy, - cztery czasowniki:
@Get()pobiera,@Post()tworzy nowy zasób,@Put()aktualizuje,@Delete()usuwa, - powtórzony
@Posttworzy dwa zasoby, powtórzony@Put- jeden, - dwukropek w trasie oznacza parametr:
@Put(':id')obsłuży/tributes/42, - trasę stałą (
search) deklaruj przed trasą z parametrem (:id), bo parametr przechwyciłby jej adres, @Param('id')czyta ze ścieżki,@Query('nazwa')czyta parametr zapytania po znaku?,@Body()czyta ciało żądania,@Path()nie istnieje;@Header()ustawia nagłówek odpowiedzi, a nagłówki żądania czyta@Headers(),- kolejność w metodzie: dekorator, nazwa, ciało,
return this.service.findAll(), - w kontrolerze nie ma logiki biznesowej - dzięki temu wywołasz ją też poza HTTP,
- kod odpowiedzi dobiera NestJS: 200, a dla
@Post- 201.
W następnej lekcji poznasz tego, komu centurion przekazuje rozkazy - serwisy, czyli miejsce, w którym mieszka prawdziwa logika. A na razie zapamiętaj: kontroler rozpoznaje żądanie i wskazuje wykonawcę - a każde dane, których potrzebuje, przychodzą jedną z trzech dróg: ścieżką, zapytaniem albo ciałem.
Kod do tej lekcji: src/legion.controller.ts
// Kontrolery - Centurionowie Struktur Imperium
import {
Controller, Get, Post, Put, Delete,
Body, Param, Query, HttpCode, Header,
ParseIntPipe, DefaultValuePipe,
} from '@nestjs/common';
console.log("Kontrolery NestJS - centurionowie przyjmujący rozkazy!");
// ===========================================
// 1. Podstawowy kontroler z dekoratorami HTTP
// ===========================================
interface Legionary {
id: number;
name: string;
rank: string;
experience: number;
}
@Controller('legiones')
export class LegionController {
private legionaries: Legionary[] = [
{ id: 1, name: 'Marcus Aurelius', rank: 'Centurio', experience: 10 },
{ id: 2, name: 'Julia Domna', rank: 'Optio', experience: 8 },
{ id: 3, name: 'Titus Flavius', rank: 'Miles', experience: 3 },
];
// GET /legiones
@Get()
findAll(
@Query('rank') rank?: string,
@Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit?: number,
) {
let result = this.legionaries;
if (rank) {
result = result.filter(l => l.rank === rank);
}
return { legionaries: result.slice(0, limit), total: result.length };
}
// GET /legiones/:id
@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
const legionary = this.legionaries.find(l => l.id === id);
if (!legionary) {
return { error: 'Legionary non inventus!' };
}
return legionary;
}
// POST /legiones
@Post()
@HttpCode(201)
create(@Body() data: Omit<Legionary, 'id'>) {
const newLegionary: Legionary = {
id: Math.max(...this.legionaries.map(l => l.id)) + 1,
...data,
};
this.legionaries.push(newLegionary);
return { message: 'Legionista zwerbowany!', legionary: newLegionary };
}
// PUT /legiones/:id
@Put(':id')
update(@Param('id', ParseIntPipe) id: number, @Body() data: Partial<Legionary>) {
const index = this.legionaries.findIndex(l => l.id === id);
if (index === -1) return { error: 'Legionary non inventus!' };
this.legionaries[index] = { ...this.legionaries[index], ...data };
return { message: 'Dane zaktualizowane!', legionary: this.legionaries[index] };
}
// DELETE /legiones/:id
@Delete(':id')
@HttpCode(204)
remove(@Param('id', ParseIntPipe) id: number) {
this.legionaries = this.legionaries.filter(l => l.id !== id);
}
// GET /legiones/search/:name
@Get('search/:name')
@Header('X-Imperium', 'Roma-Aeterna')
search(@Param('name') name: string) {
return this.legionaries.filter(
l => l.name.toLowerCase().includes(name.toLowerCase())
);
}
}
console.log("\n=== PODSUMOWANIE KONTROLERÓW ===");
console.log("@Controller('prefix') - ustawia prefiks tras");
console.log("@Get, @Post, @Put, @Delete - metody HTTP");
console.log("@Param, @Query, @Body - pobieranie danych z żądania");
console.log("@HttpCode, @Header - konfiguracja odpowiedzi");
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Jak pobrać parametr z URL w kontrolerze NestJS (np. /legion/5)?
2. Który dekorator HTTP w NestJS służy do tworzenia nowego zasobu?
3. Jak pobrać query parameter (np. ?from=rome) w kontrolerze NestJS?
Zadania praktyczne w grze
- Edytor kodu
Napisz kontroler TributesController z dekoratorem @Controller('tributes') i czterema metodami: findAll z @Get(), create z @Post(), update z @Put(':id') i remove z @Delete(':id').
- Układanie w pionie
Ułóż elementy deklaracji kontrolera w prawidłowej kolejności:
- Klikanie w kolejności
Ułóż elementy metody GET kontrolera w prawidłowej kolejności:
- Edytor kodu
Napisz kontroler LegionController z dekoratorem @Controller('legion') i dwoma endpointami GET: search z @Get('search'), który odczytuje @Query('province') province i zwraca { province }, oraz findOne z @Get(':id'), który odczytuje @Param('id') id i zwraca { id }. Endpoint search zadeklaruj przed :id, bo trasa z parametrem przechwyciłaby adres /legion/search.