Kurs NestJS · Moduł 1: Podstawy NestJS

DTO i podstawowa walidacja

4 min czytania ·
W tej lekcji8

Ave, strażniku bram! Konsul Caesar.js wie, że bezpieczeństwo imperium zaczyna się od kontroli tego, co wchodzi przez bramy. Nie możemy wpuścić do naszego systemu nieprawidłowych danych - to jak wpuszczenie szpiegów do obozu legionów! Czas poznać DTO i walidację - tarcze ochronne naszego API.

Czym jest DTO?

DTO (Data Transfer Object) to klasa, która definiuje kształt danych przesyłanych do i z naszego API. Pomyśl o DTO jak o formularzu rekrutacyjnym do legionu - każdy nowy legionista musi wypełnić odpowiednie pola, zanim zostanie przyjęty.

Bez DTO nasz kontroler przyjmuje cokolwiek - to jak otwarta brama bez straży:

// BEZ DTO - niebezpiecznie!
@Post()
create(@Body() body: any) {
  // body może zawierać cokolwiek... niebezpiecznie!
  return this.legionariesService.create(body);
}

Z DTO dokładnie definiujemy, jakie dane akceptujemy:

// Z DTO - bezpieczne jak fort rzymski!
@Post()
create(@Body() createLegionaryDto: CreateLegionaryDto) {
  return this.legionariesService.create(createLegionaryDto);
}

Tworzenie klas DTO

Stwórzmy DTO dla naszego systemu legionistów:

// dto/create-legionary.dto.ts
export class CreateLegionaryDto {
  name: string;
  rank: string;
  province: string;
  email: string;
  experience: number;
}

To jednak tylko kształt danych - nie sprawdza jeszcze, czy dane są prawidłowe. Tu wkracza walidacja!

Instalacja class-validator i class-transformer

Aby dodać walidację, potrzebujemy dwóch bibliotek:

npm install class-validator class-transformer
  • class-validator - dostarcza dekoratory walidacji (@IsString, @IsNumber, itd.)
  • class-transformer - przekształca zwykłe obiekty JSON na instancje klas DTO

Dekoratory walidacji

Teraz dodajmy walidację do naszego DTO:

// dto/create-legionary.dto.ts
import {
  IsString, IsNumber, IsEmail,
  MinLength, MaxLength, Min, Max,
  IsNotEmpty, IsOptional, IsIn
} from 'class-validator';

export class CreateLegionaryDto {
  @IsString()
  @IsNotEmpty()
  @MinLength(2)
  @MaxLength(50)
  name: string;

  @IsString()
  @IsIn(['Miles', 'Optio', 'Centurio', 'Tribunus', 'Legatus'])
  rank: string;

  @IsString()
  @IsNotEmpty()
  province: string;

  @IsEmail()
  email: string;

  @IsNumber()
  @Min(0)
  @Max(30)
  experience: number;
}

Oto najczęściej używane dekoratory walidacji:

DekoratorOpis
@IsString()Sprawdza, czy wartość to tekst
@IsNumber()Sprawdza, czy wartość to liczba
@IsEmail()Sprawdza, czy wartość to prawidłowy email
@IsNotEmpty()Sprawdza, czy pole nie jest puste
@MinLength(n)Minimalna długość tekstu
@MaxLength(n)Maksymalna długość tekstu
@Min(n)Minimalna wartość liczbowa
@Max(n)Maksymalna wartość liczbowa
@IsOptional()Pole jest opcjonalne
@IsIn([...])Wartość musi być jedną z podanych

DTO do aktualizacji - PartialType

Do częściowej aktualizacji (PATCH) możemy użyć PartialType, który sprawia, że wszystkie pola są opcjonalne:

// dto/update-legionary.dto.ts
import { PartialType } from '@nestjs/mapped-types';
import { CreateLegionaryDto } from './create-legionary.dto';

export class UpdateLegionaryDto extends PartialType(CreateLegionaryDto) {}
// Teraz wszystkie pola są opcjonalne!

PartialType pochodzi z osobnego pakietu, który doinstalujesz poleceniem npm i @nestjs/mapped-types. Automatycznie tworzy nową klasę, w której każde pole z CreateLegionaryDto staje się opcjonalne. Dzięki temu nie musimy pisać osobnego DTO z @IsOptional() na każdym polu.

ValidationPipe - globalna walidacja

Aby walidacja działała, musimy aktywować ValidationPipe w naszej aplikacji:

// main.ts
import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

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

  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,          // Usuwa pola, które nie są w DTO
    forbidNonWhitelisted: true, // Rzuca błąd, gdy są nieznane pola
    transform: true,          // Automatyczna konwersja typów
  }));

  await app.listen(3000);
}
bootstrap();

Trzy kluczowe opcje ValidationPipe:

  • whitelist: true - automatycznie usuwa pola, których nie ma w DTO (jak strażnik odrzucający podejrzane przesyłki)
  • forbidNonWhitelisted: true - zamiast cicho usuwać nieznane pola, rzuca błąd (surowsza kontrola)
  • transform: true - automatycznie konwertuje dane na odpowiednie typy (string "5" na number 5)

Kompletny przykład kontrolera z DTO

@Controller('legionaries')
export class LegionariesController {
  constructor(private readonly legionariesService: LegionariesService) {}

  @Post()
  create(@Body() createDto: CreateLegionaryDto) {
    return this.legionariesService.create(createDto);
  }

  @Patch(':id')
  update(
    @Param('id') id: string,
    @Body() updateDto: UpdateLegionaryDto,
  ) {
    return this.legionariesService.update(Number(id), updateDto);
  }
}

Kiedy ktoś prześle nieprawidłowe dane, ValidationPipe automatycznie zwróci czytelny błąd:

{
  "statusCode": 400,
  "message": [
    "name must be longer than or equal to 2 characters",
    "email must be an email",
    "experience must not be greater than 30"
  ],
  "error": "Bad Request"
}

Dlaczego DTO są ważne?

  1. Bezpieczeństwo - blokują niechciane dane zanim dotrą do logiki biznesowej
  2. Dokumentacja - jasno definiują kontrakt API
  3. Walidacja - automatyczna weryfikacja poprawności danych
  4. Typowanie - TypeScript zna kształt danych w całej aplikacji
  5. Separacja - oddzielają warstwę transportu od logiki biznesowej

DTO i walidacja to tarcza i miecz naszego imperium - chronią bramy API i zapewniają, że do systemu trafiają tylko prawidłowe dane. Każdy dobry budowniczy imperium wie, że silne mury to podstawa!

Kod do tej lekcji: src/dto-validation.ts
// DTOs i Walidacja - Tarcze Ochronne Imperium
import { IsString, IsNumber, IsEmail, MinLength, MaxLength, Min, Max, IsNotEmpty, IsOptional, IsIn } from 'class-validator';

console.log("DTOs i walidacja - strażnik bram imperium!");

// ===========================================
// 1. DTO - Data Transfer Object
// ===========================================

// Klasa DTO definiuje kształt danych
class CreateLegionaryDto {
  // @IsString()
  // @IsNotEmpty()
  // @MinLength(2)
  // @MaxLength(50)
  name: string;

  // @IsString()
  // @IsIn(['Miles', 'Optio', 'Centurio', 'Tribunus', 'Legatus'])
  rank: string;

  // @IsString()
  // @IsNotEmpty()
  province: string;

  // @IsEmail()
  email: string;

  // @IsNumber()
  // @Min(0)
  // @Max(30)
  experience: number;
}

console.log("=== CREATE LEGIONARY DTO ===");
console.log("name: @IsString, @IsNotEmpty, @MinLength(2)");
console.log("rank: @IsString, @IsIn([...])");
console.log("province: @IsString, @IsNotEmpty");
console.log("email: @IsEmail");
console.log("experience: @IsNumber, @Min(0), @Max(30)");

// ===========================================
// 2. Dekoratory walidacji
// ===========================================

console.log("\n=== DEKORATORY WALIDACJI ===");
console.log("@IsString()     - sprawdza czy tekst");
console.log("@IsNumber()     - sprawdza czy liczba");
console.log("@IsEmail()      - sprawdza czy email");
console.log("@IsNotEmpty()   - sprawdza czy niepuste");
console.log("@MinLength(n)   - minimalna długość tekstu");
console.log("@MaxLength(n)   - maksymalna długość tekstu");
console.log("@Min(n)         - minimalna wartość liczbowa");
console.log("@Max(n)         - maksymalna wartość liczbowa");
console.log("@IsOptional()   - pole opcjonalne");
console.log("@IsIn([...])    - wartość z listy");

// ===========================================
// 3. Update DTO z PartialType
// ===========================================

// import { PartialType } from '@nestjs/mapped-types';
// class UpdateLegionaryDto extends PartialType(CreateLegionaryDto) {}
// -> Wszystkie pola stają się opcjonalne!

class UpdateLegionaryDto {
  name?: string;
  rank?: string;
  province?: string;
  email?: string;
  experience?: number;
}

console.log("\n=== UPDATE DTO (PartialType) ===");
console.log("PartialType sprawia, że wszystkie pola są opcjonalne");
console.log("Idealne do PATCH - częściowa aktualizacja");

// ===========================================
// 4. ValidationPipe - globalna walidacja
// ===========================================

// W main.ts:
// app.useGlobalPipes(new ValidationPipe({
//   whitelist: true,             // Usuwa nieznane pola
//   forbidNonWhitelisted: true,  // Błąd na nieznane pola
//   transform: true,             // Konwersja typów
// }));

console.log("\n=== VALIDATION PIPE ===");
console.log("whitelist: true -> usuwa pola spoza DTO");
console.log("forbidNonWhitelisted: true -> błąd na nieznane pola");
console.log("transform: true -> konwersja typów (string -> number)");

// ===========================================
// 5. Przykład użycia w kontrolerze
// ===========================================

console.log("\n=== KONTROLER Z DTO ===");
console.log("@Post()");
console.log("create(@Body() createDto: CreateLegionaryDto) { ... }");
console.log("");
console.log("@Patch(':id')");
console.log("update(@Param('id') id, @Body() updateDto: UpdateLegionaryDto) { ... }");

// ===========================================
// 6. Przykład odpowiedzi błędnej walidacji
// ===========================================

const validationError = {
  statusCode: 400,
  message: [
    "name must be longer than or equal to 2 characters",
    "email must be an email",
    "experience must not be greater than 30"
  ],
  error: "Bad Request"
};

console.log("\n=== PRZYKŁAD BŁĘDU WALIDACJI ===");
console.log(JSON.stringify(validationError, null, 2));

console.log("\n=== PODSUMOWANIE ===");
console.log("1. DTO = kształt danych (kontrakt API)");
console.log("2. class-validator = dekoratory walidacji");
console.log("3. class-transformer = konwersja obiektów");
console.log("4. ValidationPipe = automatyczna walidacja");
console.log("5. PartialType = opcjonalne pola (do PATCH)");

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. Co oznacza skrót DTO w kontekście NestJS?

  2. 2. Który dekorator class-validator sprawdza, czy wartość jest prawidłowym adresem email?

Zadania praktyczne w grze

  • Układanie w pionie

    Uporządkuj kroki dodawania walidacji DTO w NestJS:

  • Edytor kodu

    Napisz klasę CreateLegionaryDto z polami name (@IsString, @IsNotEmpty) i email (@IsEmail)

  • Klikanie w kolejności

    Ułóż składnię aktywacji ValidationPipe w main.ts:

  • Układanie w poziomie

    Ułóż elementy tworzenia UpdateDto z PartialType:

  • Edytor kodu

    W pliku main.ts napisz funkcję setupValidation(app), która włącza w aplikacji globalną walidację: wywołuje app.useGlobalPipes() z nowym ValidationPipe, w którym opcje whitelist i transform są ustawione na true.

  1. PytanieCzym jest DTO
  2. Ułóż w kolejnościKroki dodawania walidacji DTO
  3. Zadanie z kodemTworzenie klasy DTO z walidacją
  4. Kliknij w kolejnościOpcje ValidationPipe
  5. PytanieWalidacja adresu email
  6. Ułóż w kolejnościUżycie PartialType
  7. Zadanie z kodemKonfiguracja ValidationPipe

Przydatne artykuły