Kurs NestJS · Moduł 2: Routing i cykl żądania

Pipes - kontrola przy bramie obozu

7 min czytania ·
W tej lekcji7

Do bramy obozu podjeżdża wóz z daniną. Wartownik nie pyta, kto go przysłał - to sprawdzono wcześniej, przy rogatce. Pyta o co innego: czy w skrzyniach jest to, co w liście przewozowym, czy ilości się zgadzają, czy „dwanaście" wypisane na kwicie da się w ogóle policzyć. Dopiero potem wóz wjeżdża, a kwatermistrz dostaje przeliczony, sprawdzony ładunek - nie stos worków do przejrzenia.

W tym module poznałeś już trzy mechanizmy stojące na drodze żądania: middleware, guards i interceptors. Pipes to czwarty i ostatni mechanizm cyklu żądania w NestJS - i robi coś, czego żaden z tamtych nie robi.

Dwa zadania, nie więcej

Pipes mają dwa zastosowania: walidację i transformację danych wejściowych. Warto od razu odgraniczyć je od sąsiadów, bo w cyklu żądania stoją tuż obok siebie:

  • routingiem zajmują się dekoratory @Get i @Post z pierwszej lekcji modułu, a wstępną obróbką żądania - middleware;
  • autoryzację, czyli pytanie „kto ma prawo wejść", rozstrzygają guards;
  • logowanie, cache i przerabianie odpowiedzi to praca interceptorów.

Pipe nie dotyka ani żądania jako całości, ani odpowiedzi. Dostaje jeden argument metody kontrolera i albo go przepuszcza - często przekształcony - albo rzuca wyjątek. Uruchamia się po guardach, tuż przed wejściem do metody.

ParseIntPipe - wbudowana transformacja

Parametr wyciągnięty z adresu URL jest zawsze stringiem. Żądanie /tributes/12 daje '12', nie 12:

@Controller('tributes')
export class TributeController {
  @Get(':id')
  findById(@Param('id', ParseIntPipe) id: number) {
    return this.tributeService.findById(id);
  }
}

Pipe podajemy jako drugi argument @Param: pierwszy to nazwa parametru z trasy, drugi to pipe, który ma go obsłużyć. ParseIntPipe konwertuje string na liczbę całkowitą albo rzuca wyjątek - i tylko tyle. Nie parsuje JSON-a na obiekt, nie zamienia booleana na string, nie przerabia daty na timestamp.

Wyjątek jest tu równie ważny jak sama konwersja. Po wywołaniu /tributes/abc metoda findById nie wykona się w ogóle - klient dostanie 400 Bad Request, a wewnątrz metody id ma gwarantowany typ number. To dlatego adnotacja id: number nie jest tu pobożnym życzeniem.

Rodzeństwo działa analogicznie: ParseBoolPipe dla 'true' i 'false', ParseUUIDPipe dla identyfikatorów UUID.

DTO - reguły zapisane przy polach

Przy większym ładunku pojedyncze pipes nie wystarczą. Wtedy opisujemy oczekiwany kształt danych w DTO (Data Transfer Object) - klasie, której pola noszą dekoratory z biblioteki class-validator. Dozwolone rodzaje daniny zapisujemy wcześniej w enumie TributeType:

export enum TributeType {
  GOLD = 'gold',
  SILVER = 'silver',
  GOODS = 'goods',
}

export class CreateTributeDto {
  @IsNotEmpty()
  @IsString()
  province: string;

  @IsNumber()
  @Min(1)
  amount: number;

  @IsEnum(TributeType)
  type: TributeType;
}

Kolejność zapisu jest stała: najpierw otwarcie klasy (export class CreateTributeDto {), potem dekoratory - każdy w osobnej linii - a na samym końcu pole, którego dotyczą. Dekorator stoi zawsze nad polem, nigdy obok niego, i tak samo zapiszesz każde kolejne pole tej klasy.

Każdy dekorator to jedna reguła. @IsNotEmpty() odrzuca wartość pustą, @IsString() pilnuje typu, @IsNumber() żąda liczby, @Min(1) - liczby co najmniej jeden, bo danina „zero sztuk złota" nie jest daniną, a @IsEnum(TributeType) dopuszcza wyłącznie wartości enuma (przy błędzie komunikat wymieni je wszystkie). Reguły się sumują: amount musi spełnić obie naraz.

ValidationPipe - cztery kroki

Same dekoratory niczego nie sprawdzają; to tylko opis wymagań. Wykonawcą jest ValidationPipe, a jego praca to cztery kroki, zawsze w tej kolejności:

  1. Otrzymanie surowych danych z żądania.
  2. Sprawdzenie reguł walidacji z dekoratorów DTO.
  3. Rzucenie BadRequestException, jeśli dane są niepoprawne.
  4. Zwrócenie zwalidowanych danych do handlera.

Krok trzeci przerywa cykl - handler nie zobaczy złych danych, bo w ogóle się nie uruchomi, a klient dostanie 400 z listą pól, które nie przeszły. Krok czwarty to powód, dla którego to całe zamieszanie ma sens: do metody trafia obiekt, o którym wiadomo, że spełnia wszystkie reguły.

Podpięcie do metody wygląda tak:

@Controller('tributes')
export class TributeController {
  @Post()
  createTribute(@Body(ValidationPipe) tribute: CreateTributeDto) {
    return this.tributeService.create(tribute);
  }
}

Czyta się to od lewej. createTribute(@Body( otwiera parametr pobierany z ciała żądania, ValidationPipe) domyka @Body, wskazując pipe, który ma je sprawdzić, a tribute: CreateTributeDto) nazywa parametr i podaje klasę z regułami. Bez tego ostatniego pipe nie miałby czego sprawdzać - to właśnie typ mówi mu, których dekoratorów szukać.

Rejestracja globalna

Dopisywanie ValidationPipe przy każdym @Body szybko się nudzi, a jedno pominięcie to jeden endpoint bez kontroli. Rejestrujemy go więc raz, globalnie, w pliku main.ts:

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      transform: true,
    }),
  );

  await app.listen(3000);
}

app.useGlobalPipes(new ValidationPipe()) obejmuje wszystkie endpointy aplikacji naraz. Zwróć uwagę, że to kod wykonywany przy starcie, a nie wpis w konfiguracji - dlatego nie znajdziesz tego ani w package.json (spis zależności), ani w tsconfig.json (ustawienia kompilatora), ani w .env (zmienne środowiskowe). Żaden z tych plików niczego nie uruchamia.

Dwie opcje warto włączyć od razu. whitelist: true wycina pola nieopisane w DTO - klient może przysłać isAdmin: true, ale do serwisu to nie dotrze. transform: true zamienia zwykły obiekt z JSON-a na instancję klasy DTO, a parametry trasy i zapytania z typem prostym zamienia z tekstu na ten typ: przy @Param('id') id: number dostaniesz 12, a nie '12'. Pól DTO nie przelicza - jeśli klient przyśle "amount": "500", @IsNumber() odrzuci żądanie z kodem 400. Gdy chcesz także takiej konwersji, dodaj transformOptions: { enableImplicitConversion: true }.

Własny pipe

Gdy reguła jest specyficzna dla twojej domeny, piszesz własny pipe - klasę implementującą interfejs PipeTransform z jedną metodą transform:

@Injectable()
export class TributeSealPipe implements PipeTransform {
  transform(value: string, metadata: ArgumentMetadata) {
    const seal = value.trim().toUpperCase();

    if (seal.length !== 8 || !seal.startsWith('SPQR')) {
      throw new BadRequestException(
        `Pieczęć ${value} nie jest pieczęcią imperium`,
      );
    }

    return seal;
  }
}

Metoda dostaje dwa argumenty: value - wartość do sprawdzenia - oraz metadata typu ArgumentMetadata, gdzie znajdziesz między innymi type ('body', 'query' czy 'param') i oczekiwany typ parametru. Kontrakt jest prosty: zwróć wartość albo rzuć wyjątek. Zwrócona wartość - tutaj przycięta i podniesiona do wielkich liter - trafia do metody kontrolera zamiast oryginalnej.

To znowu ta sama para zadań co na początku: walidacja (sprawdzenie długości i przedrostka) i transformacja (trim z toUpperCase). Używa się go dokładnie tak jak wbudowanego: @Param('seal', TributeSealPipe).

Podsumowanie

Wóz z daniną nie wjeżdża do obozu bez kontroli:

  • pipes służą do walidacji i transformacji danych wejściowych - nie do routingu i middleware, nie do autoryzacji i logowania, nie do cache'owania i kompresji,
  • pipe dostaje jeden argument metody i działa po guardach, tuż przed handlerem,
  • ParseIntPipe konwertuje string na liczbę całkowitą albo rzuca wyjątek; podajesz go jako drugi argument: @Param('id', ParseIntPipe) id: number,
  • pole DTO zapisujesz w kolejności: export class CreateTributeDto { → dekoratory (@IsNotEmpty(), @IsString(); ich wzajemna kolejność nie zmienia wyniku walidacji) → nazwa pola z typem,
  • reguły daniny: province z @IsString(), amount z @IsNumber() i @Min(1), type z @IsEnum(TributeType),
  • ValidationPipe w czterech krokach: surowe dane z żądania → sprawdzenie reguł z dekoratorów DTO → BadRequestException przy błędzie → zwalidowane dane do handlera,
  • w metodzie kontrolera: createTribute(@Body( → ValidationPipe) → tribute: CreateTributeDto),
  • globalnie w main.ts: app.useGlobalPipes(new ValidationPipe()) - nie w package.json, nie w tsconfig.json, nie w .env,
  • whitelist: true wycina pola spoza DTO, transform: true daje instancję DTO i zamienia proste typy parametrów trasy i zapytania,
  • własny pipe implementuje PipeTransform i metodę transform(value, metadata: ArgumentMetadata) - zwraca wartość albo rzuca wyjątek.

W następnej lekcji zaczniemy odciskać własne pieczęcie - napiszemy dekoratory szyte na miarę imperium. A na razie zapamiętaj: pipe to ostatnia brama przed twoim kodem, i wszystko, co ją minie, jest już tym, czego oczekujesz.

Kod do tej lekcji: src/pipes.ts
// Pipes w NestJS - Rzemieślnicy i Kontrolerzy Jakości
import {
  PipeTransform, Injectable, ArgumentMetadata,
  BadRequestException, ParseIntPipe, ParseBoolPipe,
  DefaultValuePipe, ValidationPipe,
} from '@nestjs/common';

console.log("Pipes - transformacja i walidacja danych!");

// ===========================================
// 1. Wbudowane Pipes
// ===========================================

// ParseIntPipe - zamienia string na number
// @Get(':id')
// findOne(@Param('id', ParseIntPipe) id: number) { ... }

// ParseBoolPipe - zamienia string na boolean
// @Get()
// findAll(@Query('active', ParseBoolPipe) active: boolean) { ... }

// DefaultValuePipe - domyślna wartość
// @Get()
// findAll(@Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number)

// ===========================================
// 2. Własny pipe - walidacja
// ===========================================

@Injectable()
export class RomanRankValidationPipe implements PipeTransform {
  private readonly validRanks = [
    'Miles', 'Optio', 'Centurio', 'Tribunus', 'Legatus',
  ];

  transform(value: any, metadata: ArgumentMetadata) {
    if (!this.validRanks.includes(value)) {
      throw new BadRequestException(
        'Ranga "' + value + '" nie istnieje w imperium! '
        + 'Dostępne rangi: ' + this.validRanks.join(', ')
      );
    }
    return value;
  }
}

// Użycie: @Param('rank', RomanRankValidationPipe) rank: string

// ===========================================
// 3. Własny pipe - transformacja
// ===========================================

@Injectable()
export class TrimPipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    if (typeof value === 'string') {
      return value.trim();
    }
    if (typeof value === 'object' && value !== null) {
      for (const key of Object.keys(value)) {
        if (typeof value[key] === 'string') {
          value[key] = value[key].trim();
        }
      }
    }
    return value;
  }
}

// ===========================================
// 4. ValidationPipe z class-validator
// ===========================================

// class CreateLegionDto {
//   @IsString() @IsNotEmpty()
//   name: string;
//
//   @IsNumber() @Min(1000) @Max(6000)
//   soldiers: number;
//
//   @IsEnum(LegionType)
//   type: LegionType;
// }

// Globalnie w main.ts:
// app.useGlobalPipes(new ValidationPipe({
//   whitelist: true,      // Usuń nieznane pola
//   forbidNonWhitelisted: true, // Błąd przy nieznanych polach
//   transform: true,      // Automatyczna transformacja typów
// }));

console.log("\n=== PODSUMOWANIE PIPES ===");
console.log("ParseIntPipe, ParseBoolPipe - wbudowane transformatory");
console.log("DefaultValuePipe - wartości domyślne");
console.log("PipeTransform - interfejs własnego pipe'a");
console.log("ValidationPipe + class-validator - walidacja DTO");
console.log("whitelist: true - usuwa nieznane pola z body");

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. 1. Jakie są dwa główne zastosowania Pipes w NestJS?

  2. 2. Co robi ParseIntPipe w NestJS?

  3. 3. Jak zarejestrować ValidationPipe globalnie w aplikacji NestJS?

Zadania praktyczne w grze

  • Edytor kodu

    Napisz endpoint @Get(':id'), który używa ParseIntPipe do walidacji parametru id

  • Układanie w pionie

    Uporządkuj kroki walidacji danych przez ValidationPipe:

  • Klikanie w kolejności

    Ułóż elementy definicji pola DTO z walidacją w prawidłowej kolejności:

  • Edytor kodu

    Napisz CreateTributeDto z polami province (@IsString), amount (@IsNumber, @Min(1)) i type (@IsEnum)

  • Układanie w poziomie

    Ułóż elementy użycia ValidationPipe w metodzie kontrolera:

  1. PytanieWprowadzenie: Dwa zastosowania Pipes
  2. PytanieWprowadzenie: Wbudowany ParseIntPipe
  3. Zadanie z kodemWprowadzenie: Użycie wbudowanych Pipes
  4. Ułóż w kolejnościWprowadzenie: Kolejność walidacji w pipe
  5. Kliknij w kolejnościWprowadzenie: Definicja DTO z walidacją
  6. PytanieWprowadzenie: ValidationPipe globalny
  7. Zadanie z kodemWprowadzenie: DTO z dekoratorami walidacji
  8. Ułóż w kolejnościWprowadzenie: Użycie ValidationPipe w endpoincie

Przydatne artykuły