Kurs NestJS · Moduł 10: Walidacja danych

Projekt - kompletny system walidacji Imperium

6 min czytania ·
W tej lekcji8

Osiem lekcji tego modułu poznawało strażników pojedynczo: dekoratory z class-validator, ValidationPipe, transformacje, walidację zagnieżdżoną, własne walidatory i grupy. Projekt jest miejscem, w którym staną razem przy jednej bramie - a wtedy okazuje się, że najważniejsze jest coś, o czym żadna lekcja z osobna nie mówiła: kolejność, w jakiej działają.

Zbudujesz system zarządzania legionami z pełnym CRUD-em i walidacją danych wejściowych: DTO legionu, legionisty i broni, własny walidator, transformacje odpowiedzi i globalna konfiguracja bramy.

Kolejność, która tłumaczy resztę

Zanim napiszesz pierwszą linijkę, zapamiętaj drogę, którą przebywa żądanie:

  1. Przychodzi zwykły obiekt JSON - bez klas, bez typów, wszystko jest tekstem albo liczbą.
  2. class-transformer zamienia go w instancję klasy DTO, wykonując po drodze @Type i @Transform.
  3. class-validator sprawdza dekoratory walidacji na tej instancji.
  4. Dopiero wynik trafia do handlera.

Stąd wniosek, który oszczędzi ci wieczoru: transformacja dzieje się przed walidacją. @Transform(({ value }) => value.trim()) obetnie spacje, a dopiero potem @MinLength(2) policzy znaki - więc " A " zostanie odrzucone, choć na oko ma pięć znaków.

Krok 1 - enumy i pierwsze DTO

// enums.ts
export enum LegionaryRank {
  MILES = 'miles',
  OPTIO = 'optio',
  CENTURIO = 'centurio',
  TRIBUNUS = 'tribunus',
  LEGATUS = 'legatus',
}

export enum WeaponType {
  GLADIUS = 'gladius',
  PILUM = 'pilum',
  SCUTUM = 'scutum',
  PUGIO = 'pugio',
}

// weapon.dto.ts
export class CreateWeaponDto {
  @IsString()
  @IsNotEmpty()
  name: string;

  @IsEnum(WeaponType)
  type: WeaponType;

  @IsNumber()
  @Min(1)
  @Max(100)
  damage: number;
}

Zwróć uwagę, że rangi i typy broni są enumami, a nie uniami typu 'miles' | 'optio'. Powód jest ten sam, dla którego cała ta biblioteka istnieje: typy TypeScriptu znikają przy kompilacji. Unia nie zostawia po sobie nic, czego walidator mógłby o cokolwiek zapytać w czasie działania programu; enum zostaje zwykłym obiektem, więc @IsEnum(WeaponType) ma z czym porównywać.

@Min i @Max przy damage to nie ozdobnik. Bez nich klient przyśle damage: -5 albo damage: 999999 i baza przyjmie obie wartości bez mrugnięcia.

Krok 2 - walidacja zagnieżdżona

export class CreateLegionaryDto {
  @IsString()
  @IsNotEmpty()
  @MinLength(2)
  @MaxLength(50)
  @Transform(({ value }) => value.trim())
  name: string;

  @IsEnum(LegionaryRank)
  rank: LegionaryRank;

  @IsNumber()
  @Min(16)
  @Max(65)
  age: number;

  @Matches(/^LEG-[A-Z]{2,4}-\d{4}$/, {
    message: 'ID musi mieć format LEG-XX-0000',
  })
  militaryId: string;

  @IsArray()
  @ArrayMinSize(1)
  @IsString({ each: true })
  skills: string[];

  @ValidateNested()
  @Type(() => CreateWeaponDto)
  primaryWeapon: CreateWeaponDto;

  @IsOptional()
  @ValidateNested()
  @Type(() => CreateWeaponDto)
  secondaryWeapon?: CreateWeaponDto;
}

Tutaj kryje się najczęstsza pułapka całego modułu. @ValidateNested() bez @Type() nie zadziała - i nie zgłosi błędu. Bez @Type transformer zostawia w polu primaryWeapon zwykły obiekt, a nie instancję CreateWeaponDto; walidator zagląda do niego, nie znajduje żadnych dekoratorów i uznaje, że wszystko w porządku. Broń o ujemnej sile przejdzie przez bramę, bo strażnika nikt nie postawił.

Dwa dopiski warte uwagi. @IsString({ each: true }) sprawdza każdy element tablicy, a nie tablicę jako całość - bez each reguła odnosiłaby się do samego pola skills. @IsOptional() musi stać przed pozostałymi dekoratorami pola opcjonalnego: mówi walidatorowi, żeby pominął resztę reguł, gdy wartości nie ma, zamiast wymagać jej.

Krok 3 - tablica zagnieżdżonych obiektów

export class CreateLegionDto {
  @IsString()
  @IsNotEmpty()
  @MinLength(3)
  name: string;

  @IsEnum(LegionStatus)
  status: LegionStatus;

  @IsNumber()
  @Min(1000)
  @Max(6000)
  maxSoldiers: number;

  @IsArray()
  @ArrayMinSize(1)
  @ValidateNested({ each: true })
  @Type(() => CreateLegionaryDto)
  soldiers: CreateLegionaryDto[];
}

Różnica wobec poprzedniego kroku mieści się w dwóch słowach: { each: true }. Bez tego @ValidateNested() sprawdziłby tablicę jako jeden obiekt - czyli w praktyce nic. Z tym zapisem każdy legionista przechodzi pełną walidację osobno, wraz ze swoją bronią, bo zagnieżdżenie działa rekurencyjnie: legion → legionista → broń.

Warto zdać sobie sprawę z ceny. Legion na sześć tysięcy żołnierzy, każdy z dwiema sztukami broni, to kilkadziesiąt tysięcy sprawdzeń przy jednym żądaniu. Przy takich rozmiarach dodaje się @ArrayMaxSize i rozważa przyjmowanie żołnierzy osobnym endpointem - walidacja jest tania, ale nie darmowa.

Krok 4 - własny walidator

@ValidatorConstraint({ async: false })
class IsValidMilitaryIdConstraint implements ValidatorConstraintInterface {
  validate(value: string): boolean {
    if (!value) return false;
    const parts = value.split('-');
    if (parts.length !== 3) return false;
    if (parts[0] !== 'LEG') return false;
    const numericPart = parseInt(parts[2], 10);
    return numericPart > 0 && numericPart <= 9999;
  }

  defaultMessage(): string {
    return 'Niepoprawny identyfikator wojskowy';
  }
}

export function IsValidMilitaryId(options?: ValidationOptions) {
  return function (object: object, propertyName: string) {
    registerDecorator({
      target: object.constructor,
      propertyName,
      options,
      validator: IsValidMilitaryIdConstraint,
    });
  };
}

Własny walidator zawsze ma dwie części: klasę z regułą i funkcję-dekorator, która ją rejestruje. Klasa dostarcza validate zwracające wartość logiczną oraz defaultMessage z komunikatem; funkcja pozwala używać reguły tak samo jak wbudowanych, przez @IsValidMilitaryId().

Po co to, skoro @Matches z kroku drugiego robi podobną rzecz? Bo wyrażenie regularne sprawdza kształt, a nie sens. Tutaj dochodzi warunek, że numer mieści się w zakresie od 1 do 9999 - reguła należąca do domeny, nie do składni. Gdy takich warunków przybędzie, wszystkie mają jedno miejsce, a komunikat błędu można napisać po ludzku. Flaga { async: false } mówi, że reguła nie sięga do bazy; przy sprawdzeniu unikalności ustawisz true i validate zwróci Promise.

Krok 5 - DTO odpowiedzi

export class LegionaryResponseDto {
  @Expose()
  name: string;

  @Expose()
  rank: string;

  @Expose()
  @Transform(({ value }) => (value > 10 ? 'Veteranus' : 'Tiro'))
  experienceLevel: string;

  @Exclude()
  secretMissionCode: string;

  @Exclude()
  salary: number;
}

Walidacja pilnuje tego, co wchodzi. Tu pilnujemy tego, co wychodzi - a to równie ważne, bo wyciek żołdu i kodów misji nie zgłosi się sam. @Expose() przepuszcza pole, @Exclude() je usuwa, @Transform liczy wartość pochodną w locie.

Jedna rzecz, o której łatwo zapomnieć: same dekoratory nic nie zrobią. Aby zadziałały, kontroler musi mieć @UseInterceptors(ClassSerializerInterceptor) albo trzeba wywołać plainToInstance z opcją excludeExtraneousValues: true. Bez tego serwis zwróci zwykły obiekt, a @Exclude() pozostanie adnotacją bez skutku - i właśnie tak wyciekają dane, o których wszyscy myśleli, że są ukryte.

Krok 6 - konfiguracja bramy

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

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

  await app.listen(3000);
}

Cztery opcje, cztery decyzje. whitelist: true wycina pola, których nie ma w DTO. forbidNonWhitelisted: true idzie dalej i odrzuca takie żądanie z błędem 400 - to wybór surowszy, a przez to uczciwszy: klient dowie się, że przysłał coś nieoczekiwanego, zamiast myśleć, że zapisałeś jego pole.

transform: true sprawia, że do handlera trafia instancja klasy DTO, nie zwykły obiekt - bez tego @Type i @Transform z wcześniejszych kroków pozostają martwe. enableImplicitConversion: true dokłada konwersję typów prostych: "25" z parametru zapytania stanie się liczbą 25, bo typ pola mówi number. Tę ostatnią opcję włączaj świadomie - bywa wygodna, ale potrafi zamienić "0" na 0, a "false" na true.

Co oddajesz

Projekt jest gotowy, gdy spełnia pięć warunków:

  1. CRUD dla legionów - endpointy tworzenia, odczytu, aktualizacji i usuwania.
  2. DTO z class-validator dla każdego wejścia, z walidacją zagnieżdżoną i tablicami.
  3. Co najmniej jeden własny walidator zarejestrowany przez registerDecorator.
  4. Transformacje z class-transformer na wejściu (@Type, @Transform) i na wyjściu (@Expose, @Exclude).
  5. Globalny ValidationPipe z opcjami z kroku szóstego.

Sprawdź na koniec dwie rzeczy, które przechodzą niezauważone najczęściej: czy każde @ValidateNested ma obok siebie @Type, i czy pola oznaczone @Exclude() naprawdę nie pojawiają się w odpowiedzi. Jedno i drugie zawodzi po cichu - bez błędu, bez ostrzeżenia, aż do dnia, w którym ktoś to zauważy.

Prześlij link do repozytorium, gdy skończysz.

Kod do tej lekcji: src/complete-validation.ts
// Projekt główny - Kompletny system walidacji Imperium
import {
  IsString, IsNotEmpty, IsEnum, IsNumber,
  Min, Max, MinLength, MaxLength, IsArray,
  ArrayMinSize, ValidateNested, IsOptional, Matches,
  ValidatorConstraint, ValidatorConstraintInterface,
  registerDecorator, ValidationOptions,
} from 'class-validator';
import { Type, Transform, Exclude, Expose } from 'class-transformer';

// === ENUMY ===
enum LegionaryRank {
  MILES = 'miles',
  OPTIO = 'optio',
  CENTURIO = 'centurio',
  LEGATUS = 'legatus',
}

enum WeaponType {
  GLADIUS = 'gladius',
  PILUM = 'pilum',
  SCUTUM = 'scutum',
}

// === CUSTOM VALIDATOR ===
// TODO: Zaimplementuj IsValidMilitaryId
@ValidatorConstraint({ async: false })
class IsValidMilitaryIdConstraint
  implements ValidatorConstraintInterface {
  validate(value: string): boolean {
    if (!value) return false;
    return /^LEG-[A-Z]{2,4}-\d{4}$/.test(value);
  }
  defaultMessage(): string {
    return 'Niepoprawny ID wojskowy!';
  }
}

// === WEAPON DTO ===
class CreateWeaponDto {
  @IsString()
  @IsNotEmpty()
  name: string;

  @IsEnum(WeaponType)
  type: WeaponType;

  @IsNumber()
  @Min(1)
  @Max(100)
  damage: number;
}

// === LEGIONARY DTO ===
// TODO: Uzupełnij brakujące dekoratory
class CreateLegionaryDto {
  @IsString()
  @IsNotEmpty()
  @MinLength(2)
  @Transform(({ value }) => value.trim())
  name: string;

  @IsEnum(LegionaryRank)
  rank: LegionaryRank;

  @IsNumber()
  @Min(16)
  @Max(65)
  age: number;

  // TODO: Dodaj walidację zagnieżdżoną dla broni
  @ValidateNested()
  @Type(() => CreateWeaponDto)
  weapon: CreateWeaponDto;

  @IsArray()
  @ArrayMinSize(1)
  @IsString({ each: true })
  skills: string[];
}

// === RESPONSE DTO ===
class LegionaryResponse {
  @Expose()
  name: string;

  @Expose()
  rank: string;

  @Exclude()
  salary: number;
}

console.log('Kompletny system walidacji Imperium gotowy!');

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

  1. Projekt do wysłaniaPrześlij swój system walidacji
  2. WideoPodsumowanie modułu

Przydatne artykuły