Kurs NestJS · Moduł 10: Walidacja danych
Projekt - kompletny system walidacji Imperium
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:
- Przychodzi zwykły obiekt JSON - bez klas, bez typów, wszystko jest tekstem albo liczbą.
class-transformerzamienia go w instancję klasy DTO, wykonując po drodze@Typei@Transform.class-validatorsprawdza dekoratory walidacji na tej instancji.- 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:
- CRUD dla legionów - endpointy tworzenia, odczytu, aktualizacji i usuwania.
- DTO z
class-validatordla każdego wejścia, z walidacją zagnieżdżoną i tablicami. - Co najmniej jeden własny walidator zarejestrowany przez
registerDecorator. - Transformacje z
class-transformerna wejściu (@Type,@Transform) i na wyjściu (@Expose,@Exclude). - Globalny
ValidationPipez 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?