Kurs NestJS · Moduł 1: Podstawy NestJS

Kontrolery - centurionowie Imperium

5 min czytania ·
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 @Controller to prefiks trasy wspólny dla wszystkich metod klasy,
  • cztery czasowniki: @Get() pobiera, @Post() tworzy nowy zasób, @Put() aktualizuje, @Delete() usuwa,
  • powtórzony @Post tworzy 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. 1. Jak pobrać parametr z URL w kontrolerze NestJS (np. /legion/5)?

  2. 2. Który dekorator HTTP w NestJS służy do tworzenia nowego zasobu?

  3. 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.

  1. PytanieDekorator @Get z parametrem
  2. PytanieMetoda HTTP do tworzenia zasobu
  3. Zadanie z kodemKontroler z metodami CRUD
  4. Ułóż w kolejnościDeklaracja kontrolera NestJS
  5. PytanieParametry zapytania w NestJS
  6. Kliknij w kolejnościBudowa metody GET kontrolera
  7. Zadanie z kodemParametry zapytania i ścieżki

Przydatne artykuły