Kurs NestJS · Moduł 3: TypeORM i bazy danych
Database Validation - kontrola jakości danych
W tej lekcji8
Do skarbca trafił wczoraj legionista bez imienia. Dziś - dwa identyczne wpisy tego samego tributu. Konsul Caesar.js jest wściekły: przecież walidujemy dane w DTO! Owszem - ale walidacja w warstwie API chroni tylko jedną bramę. Dane wchodzą do bazy także innymi drogami: przez seeder, przez inny serwis, przez ręczne zapytanie administratora. Dlatego dojrzały system ustawia strażników warstwami: DTO sprawdza kształt żądania, serwis pilnuje reguł biznesowych, a baza danych jest ostatnią linią obrony - murem, którego nie obejdzie nikt. W tej lekcji budujemy właśnie ten mur.
Reguły wprost w kolumnach
Pierwsza linia muru to definicje kolumn. Dekorator @Column przyjmuje opcje, które baza zamieni na twarde ograniczenia:
@Entity()
export class Legionary {
@Column({ length: 100, nullable: false })
name: string;
@Column({ unique: true })
codeName: string;
@Column({ type: 'int', default: 0 })
tributeCount: number;
@Column({ type: 'boolean', default: true })
isActive: boolean;
}Przeczytajmy te opcje jak rozkazy dla bazy. nullable: false to SQL-owe NOT NULL - rekord bez imienia zostanie odrzucony, zanim dotknie tabeli. unique: true zakłada ograniczenie unikalności: drugi legionista o tym samym codeName wywoła błąd bazy, nie cichy duplikat. default uzupełnia wartość, gdy jej nie podano - nowy legionista startuje z zerem tributów, bez pisania tego w kodzie. A type i length dobierają typ kolumny do danych: liczba całkowita dla licznika, tekst o ograniczonej długości dla imienia. Zauważ, że te reguły działają zawsze - niezależnie od tego, którą drogą dane wchodzą.
Indeksy - spis treści skarbca
Skoro codeName ma być unikalny, baza i tak zbudowała dla niego indeks. Ale indeks przyda się także tam, gdzie często szukamy, choć unikalności nie wymagamy - dekorator @Index zakładamy wtedy sami:
@Entity()
@Index(['rank', 'isActive'])
export class Legionary {
@Index()
@Column()
lastName: string;
}Indeks działa jak spis treści księgi inwentarzowej: zamiast kartkować całą tabelę, baza skacze prosto do właściwej strony. Pojedynczy @Index() nad kolumną przyspiesza wyszukiwanie po lastName; indeks złożony nad klasą - zapytania filtrujące jednocześnie po randze i aktywności. To najprostsza optymalizacja zapytań, jaką znasz z tej lekcji: zero zmian w kodzie serwisu, a zapytania z where po tych kolumnach przestają skanować całą tabelę. Cena jest jedna - każdy zapis musi zaktualizować także indeks - dlatego indeksujemy kolumny, po których naprawdę szukamy, a nie wszystkie.
Znaczniki czasu - kronika automatyczna
Kiedy rekord powstał? Kiedy go ostatnio zmieniano? Tych dwóch kolumn nie wypełniamy nigdy ręcznie:
@CreateDateColumn()
createdAt: Date;
@UpdateDateColumn()
updatedAt: Date;@CreateDateColumn dostaje datę raz, przy tworzeniu rekordu, i już się nie zmienia. @UpdateDateColumn odświeża się przy każdym zapisie. Kronika prowadzi się sama - a Ty zyskujesz odpowiedź na pytanie "co się tu ostatnio działo", zanim ktokolwiek je zada.
Hooki encji - rytuał przed zapisem
Czasem przed zapisem trzeba coś dopilnować: przyciąć spacje, znormalizować wielkość liter, wyliczyć pole pochodne. Do tego służą hooki - metody encji oznaczone dekoratorem, które TypeORM wywoła sam w odpowiednim momencie:
@Entity()
export class Legionary {
@Column()
codeName: string;
@BeforeInsert()
@BeforeUpdate()
normalizeCodeName() {
this.codeName = this.codeName.trim().toLowerCase();
}
}@BeforeInsert odpala metodę tuż przed pierwszym zapisem rekordu, @BeforeUpdate - przed każdą aktualizacją. Tutaj oba dekoratory wiszą nad jedną metodą, więc normalizacja zadziała w obu sytuacjach: niezależnie od tego, jak niechlujnie wpisano codeName, do bazy trafi wersja przycięta i pisana małymi literami. Ważna granica: hook mieszka w encji i widzi tylko ją samą. Gdy potrzebujesz reagować na zapisy wielu encji w jednym miejscu (na przykład logować każdą zmianę w skarbcu), TypeORM oferuje subscribers - osobne klasy nasłuchujące zdarzeń całej bazy. Zapamiętaj podział: hook - rytuał jednej encji, subscriber - obserwator całego systemu.
Soft delete - wygnanie zamiast egzekucji
Rozkaz "usuń legionistę" bywa pochopny. Zwykłe delete kasuje rekord bezpowrotnie - a razem z nim historię tributów i powiązania. Dlatego dojrzałe systemy stosują soft delete: rekord dostaje znacznik usunięcia, ale fizycznie zostaje w tabeli. W TypeORM wystarczy jedna kolumna:
@Entity()
export class Legionary {
@DeleteDateColumn()
deletedAt: Date;
}
// usunięcie miękkie - ustawia deletedAt, rekord zostaje
await legionaryRepository.softDelete(legionaryId);
// przywrócenie - czyści deletedAt
await legionaryRepository.restore(legionaryId);
// znalezienie także usuniętych
const all = await legionaryRepository.find({ withDeleted: true });Obecność @DeleteDateColumn zmienia zachowanie całego repozytorium: softDelete wpisuje datę do deletedAt, a każde zwykłe find zaczyna automatycznie pomijać rekordy z ustawioną datą - usunięty legionista znika z wyników, choć w tabeli wciąż jest. restore czyści znacznik i legionista wraca do służby. A gdy audytor chce zobaczyć wszystkich, także wygnanych - dodaje opcję withDeleted: true. Egzekucja stała się wygnaniem: odwracalnym i zostawiającym ślad.
Cascade - los rekordów powiązanych
Została ostatnia decyzja strażnika: co z tributami, gdy ich właściciel znika? Odpowiedź zapisujemy w definicji relacji:
@OneToMany(() => Tribute, (tribute) => tribute.legionariusze, {
cascade: true,
})
tributes: Tribute[];
@ManyToOne(() => Legionary, { onDelete: 'CASCADE' })
legionariusze: Legionary;To dwie różne kaskady i warto je rozróżniać. cascade: true działa przy zapisie: zapisując legionistę z nowymi tributami w tablicy, TypeORM zapisze i jego, i je - jednym ruchem. onDelete: 'CASCADE' działa przy usuwaniu, po stronie bazy: gdy legionista znika naprawdę, baza sama usuwa jego tributy, nie zostawiając rekordów-sierot. Alternatywy dla 'CASCADE' to między innymi 'SET NULL' - tribut zostaje, ale traci właściciela. Wybór należy do Ciebie - ale podejmij go świadomie, bo kaskada usuwania to najostrzejsze narzędzie w tej lekcji.
findAndCount - paginacja po stronie repozytorium
Na koniec spinamy kontrolę jakości z czymś, co znasz z lekcji o Query Builderze: podawaniem wyników porcjami. Repozytorium ma do tego gotową parę metod w jednej:
const [legionaries, total] = await legionaryRepository.findAndCount({
where: { isActive: true },
order: { name: 'ASC' },
skip: (page - 1) * limit,
take: limit,
});findAndCount zwraca tablicę dwuelementową: listę wyników i łączną liczbę pasujących rekordów. Zapis const [legionaries, total] = ... to destrukturyzacja - rozpakowujemy parę do dwóch nazwanych zmiennych w jednej linii. Reszta wygląda jak zwykłe find: skip pomija poprzednie strony, take pobiera porcję. To repozytoryjny bliźniak getManyAndCount() z Query Buildera - prostszy zapis na prostsze przypadki, a gdy warunki się komplikują, wracasz do buildera.
Podsumowanie
Mur wokół skarbca stoi. Ułożyłeś go warstwami:
- opcje
@Column:nullable,unique,default,typeilength- twarde reguły egzekwowane przez samą bazę, @Index- spis treści dla kolumn, po których szukasz; przyspiesza odczyty kosztem zapisów,@CreateDateColumni@UpdateDateColumn- kronika prowadząca się sama,@BeforeInserti@BeforeUpdate- rytuał encji przed zapisem; subscribers - obserwator zdarzeń całej bazy,@DeleteDateColumnzsoftDelete,restoreiwithDeleted- wygnanie zamiast egzekucji,cascadeprzy zapisie ionDelete: 'CASCADE'przy usuwaniu - świadomy los rekordów powiązanych,findAndCountz destrukturyzacją[wyniki, licznik]- paginacja bez Query Buildera.
Przed Tobą projekt kończący moduł: system inwentaryzacji tributów, w którym te strażnicze mechanizmy spotkają się w jednym kodzie. A na razie zapamiętaj: walidacja w DTO chroni bramę, ale to reguły w bazie są murem - działają zawsze, niezależnie od tego, którędy dane próbują wejść.
Kod do tej lekcji: src/database-validation.ts
// Database Validation - Kontrola Jakosci Danych
import {
Entity, Column, PrimaryGeneratedColumn, Index,
CreateDateColumn, UpdateDateColumn, DeleteDateColumn,
Check, BeforeInsert, BeforeUpdate, AfterInsert,
} from 'typeorm';
console.log("Walidacja bazy danych - ostatnia linia obrony!");
// ===========================================
// 1. Constraints na kolumnach
// ===========================================
@Entity('tribute_records')
@Index(['provincia', 'year']) // Indeks zlozony
export class TributeRecord {
@PrimaryGeneratedColumn()
id: number;
@Column({ length: 100 })
provincia: string;
@Column({ type: 'decimal', precision: 12, scale: 2 })
@Check('"amount" > 0') // Wartosc musi byc dodatnia
amount: number;
@Column({ type: 'int' })
year: number;
@Index() // Indeks na kolumnie
@Column({ length: 100 })
collector: string;
@Column({ type: 'enum', enum: ['gold', 'silver', 'goods'], default: 'gold' })
type: string;
@CreateDateColumn()
createdAt: Date;
}
// ===========================================
// 2. Entity hooks (lifecycle events)
// ===========================================
@Entity('centurions')
export class Centurion {
@PrimaryGeneratedColumn()
id: number;
@Column()
name: string;
@Column()
rank: string;
@Column({ default: 0 })
experience: number;
@Column({ nullable: true })
slug: string;
@CreateDateColumn()
createdAt: Date;
@UpdateDateColumn()
updatedAt: Date;
@BeforeInsert()
generateSlug() {
if (this.name) {
this.slug = this.name.toLowerCase().replace(/ /g, '-');
}
}
@BeforeUpdate()
validateExperience() {
if (this.experience < 0) {
this.experience = 0;
}
}
@AfterInsert()
logCreation() {
console.log('Nowy centurion zaciagniety: ' + this.name);
}
}
// ===========================================
// 3. Soft delete
// ===========================================
@Entity('decrees')
export class Decree {
@PrimaryGeneratedColumn()
id: number;
@Column({ length: 200 })
title: string;
@Column({ type: 'text' })
content: string;
@Column({ type: 'boolean', default: true })
isActive: boolean;
@CreateDateColumn()
createdAt: Date;
@UpdateDateColumn()
updatedAt: Date;
@DeleteDateColumn() // Soft delete - nie usuwaj naprawde
deletedAt: Date;
}
// Uzycie soft delete:
// await decreeRepo.softDelete(id); // Ustawia deletedAt
// await decreeRepo.restore(id); // Przywraca
// await decreeRepo.find(); // Pomija soft-deleted
// await decreeRepo.find({ withDeleted: true }); // Wszystkie
console.log("\n=== PODSUMOWANIE WALIDACJI DB ===");
console.log("@Check() - constrainty na poziomie bazy danych");
console.log("@Index() - indeksy przyspieszajace wyszukiwanie");
console.log("@BeforeInsert/@BeforeUpdate - hooki cyklu zycia");
console.log("@DeleteDateColumn - soft delete (nie usuwaj naprawde)");
console.log("unique: true - unikalnosc kolumny");
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Jak dodać walidację na poziomie encji w TypeORM z class-validator?
2. Jak oznaczyć kolumnę jako unikalną w encji TypeORM?
To 2 z 6 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Napisz encję Province z @Index() na nazwie, @Column({ unique: true }) dla kodu i dekoratorami @IsString(), @Length(2, 100)
- Układanie w pionie
Uporządkuj warstwy walidacji danych od zewnętrznej do wewnętrznej:
- Klikanie w kolejności
Ułóż elementy definicji kolumny z wartością domyślną i NOT NULL:
- Edytor kodu
Napisz encję z @BeforeInsert() który ustawia createdAt na new Date() i @BeforeUpdate() który ustawia updatedAt
- Układanie w poziomie
Ułóż elementy dekoratora @Index dla encji z wieloma kolumnami:
- Układanie w pionie
Uporządkuj typy kolumn TypeORM od najprostszego do najbardziej złożonego:
- Edytor kodu
Napisz encję z @CreateDateColumn(), @UpdateDateColumn() i @DeleteDateColumn() dla soft delete
- Klikanie w kolejności
Ułóż elementy soft delete za pomocą repozytorium w prawidłowej kolejności:
- Układanie w poziomie
Ułóż elementy zapytania o rekordy włącznie z soft-deleted:
- Układanie w pionie
Uporządkuj techniki optymalizacji zapytań od najprostszej do najbardziej zaawansowanej:
- Edytor kodu
Napisz metodę findPaginated(page, limit), która używa findAndCount z skip i take do paginacji legionistów
- Układanie w poziomie
Ułóż elementy destrukturyzacji wyniku findAndCount:
Zadania po tej lekcji
- PytanieWalidacja na poziomie encji
- PytanieUnique constraint
- Zadanie z kodemEncja z walidacją i indeksami
- Ułóż w kolejnościWarstwy walidacji danych w NestJS
- Kliknij w kolejnościDefinicja kolumny z NOT NULL i default
- PytanieHook BeforeInsert
- Zadanie z kodemEntity hooks i subscribers
- Ułóż w kolejnościDekorator Index na encji
- Ułóż w kolejnościTypy kolumn od najprostszego do najbardziej złożonego
- PytanieSoft delete w TypeORM
- Zadanie z kodemEncja z soft delete i timestampami
- Kliknij w kolejnościSoft delete z repozytorium
- Ułóż w kolejnościOdzyskanie soft-deleted rekordów
- PytanieCascade w relacjach
- Ułóż w kolejnościOptymalizacja zapytań bazy danych
- Zadanie z kodemPaginacja wyników
- PytanieMetoda findAndCount
- Ułóż w kolejnościDestrukturyzacja findAndCount