Pipes - kontrola przy bramie obozu

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

'12'

12

1@Controller('tributes')
2export class TributeController {
3  @Get(':id')
4  findById(@Param('id', ParseIntPipe) id: number) {
5    return this.tributeService.findById(id);
6  }
7}

Pipe podajemy jako drugi argument

@Param

ParseIntPipe

Wyjątek jest tu równie ważny jak sama konwersja. Po wywołaniu

/tributes/abc

findById

400 Bad Request

id

number

id: number

Rodzeństwo działa analogicznie:

ParseBoolPipe

'true'

'false'

ParseUUIDPipe

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

1export class CreateTributeDto {
2  @IsNotEmpty()
3  @IsString()
4  province: string;
5
6  @IsNumber()
7  @Min(1)
8  amount: number;
9
10  @IsEnum(['gold', 'silver', 'goods'])
11  type: string;
12}

Kolejność zapisu jest stała: najpierw otwarcie klasy (

export class CreateTributeDto {

Każdy dekorator to jedna reguła.

@IsNotEmpty()

@IsString()

@IsNumber()

@Min(1)

@IsEnum(['gold', 'silver', 'goods'])

amount

ValidationPipe - cztery kroki

Same dekoratory niczego nie sprawdzają; to tylko opis wymagań. Wykonawcą jest

ValidationPipe

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

Podpięcie do metody wygląda tak:

1@Post()
2createTribute(@Body(ValidationPipe) tribute: CreateTributeDto) {
3  return this.tributeService.create(tribute);
4}

Czyta się to od lewej.

createTribute(@Body(

ValidationPipe)

@Body

tribute: CreateTributeDto)

Rejestracja globalna

Dopisywanie

ValidationPipe

@Body

main.ts

1async function bootstrap() {
2  const app = await NestFactory.create(AppModule);
3
4  app.useGlobalPipes(
5    new ValidationPipe({
6      whitelist: true,
7      transform: true,
8    }),
9  );
10
11  await app.listen(3000);
12}

app.useGlobalPipes(new ValidationPipe())

package.json

tsconfig.json

.env

Dwie opcje warto włączyć od razu.

whitelist: true

isAdmin: true

transform: true

amount

number

'500'

Własny pipe

Gdy reguła jest specyficzna dla twojej domeny, piszesz własny pipe - klasę implementującą interfejs

PipeTransform

transform

1@Injectable()
2export class TributeSealPipe implements PipeTransform {
3  transform(value: string, metadata: ArgumentMetadata) {
4    const seal = value.trim().toUpperCase();
5
6    if (seal.length !== 8 || !seal.startsWith('SPQR')) {
7      throw new BadRequestException(
8        `Pieczęć ${value} nie jest pieczęcią imperium`,
9      );
10    }
11
12    return seal;
13  }
14}

Metoda dostaje dwa argumenty:

value

metadata

ArgumentMetadata

type

'body'

'query'

'param'

To znowu ta sama para zadań co na początku: walidacja (sprawdzenie długości i przedrostka) i transformacja (

trim

toUpperCase

@Param('seal', TributeSealPipe)

Podsumowanie

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

• 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 {

  →

  @IsNotEmpty()

  →

  @IsString()

  → nazwa pola z typem,
• reguły daniny:

  province

  z

  @IsString()

  ,

  amount

  z

  @IsNumber()

  i

  @Min(1)

  ,

  type

  z

  @IsEnum(['gold', 'silver', 'goods'])

  ,

• 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 z poprawnymi typami,
• 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.