Kurs NestJS · Moduł 1: Podstawy NestJS
DTO i podstawowa walidacja
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:
| Dekorator | Opis |
|---|---|
@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?
- Bezpieczeństwo - blokują niechciane dane zanim dotrą do logiki biznesowej
- Dokumentacja - jasno definiują kontrakt API
- Walidacja - automatyczna weryfikacja poprawności danych
- Typowanie - TypeScript zna kształt danych w całej aplikacji
- 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. Co oznacza skrót DTO w kontekście NestJS?
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.