Kurs NestJS · Moduł 3: TypeORM i bazy danych
Relacje w bazie danych - więzy legionu
W tej lekcji5
Masz już tabelę legionistów i tabelę legionów. Każda z osobna trzyma się dobrze - ale skąd wiadomo, kto pod kim służy? Można by wpisać nazwę legionu w kolumnę tekstową przy każdym legioniście. Do pierwszej literówki: "Legio X Equestris" i "Legio X Equestriss" to dla bazy dwa różne legiony, a Ty właśnie rozbiłeś kohortę na dwie.
Rzymianie znali lepszy sposób. Legionista nie nosi przy sobie nazwy legionu - nosi jego numer. Jeden legion, jeden numer, wszyscy wskazują na ten sam wpis w rejestrze. To jest relacja: powiązanie oparte na identyfikatorze, a nie na przepisywanym tekście.
W tej lekcji poznasz trzy rodzaje takich więzów i nauczysz się je czytać ze strony kodu.
Jeden do wielu - legion i jego legioniści
Zacznijmy od najczęstszego układu. Legion ma wielu legionistów; legionista należy do jednego legionu. Ta relacja ma dwie strony i obie trzeba opisać - każdą w swojej encji:
@Entity()
export class Legion {
@OneToMany(() => Legionary, (legionary) => legionary.legion)
legionaries: Legionary[];
}
@Entity()
export class Legionary {
@ManyToOne(() => Legion, (legion) => legion.legionaries)
legion: Legion;
}Kluczowa jest zasada, po której poznasz, gdzie co postawić: dekorator opisuje stronę, na której stoi. Legion jest "jednym", a ma "wielu" legionistów - więc w encji Legion stoi @OneToMany, a pole jest tablicą. Legionista jest jednym z "wielu" i należy do "jednego" legionu - w encji Legionary stoi @ManyToOne, a pole jest pojedyncze. Jeśli kiedykolwiek się zawahasz, przeczytaj zdanie od strony encji, którą właśnie piszesz: "legionista należy do jednego legionu" - i masz @ManyToOne.
Przyjrzyjmy się dwóm argumentom dekoratora, bo oba są obowiązkowe i oba mylą. Pierwszy, () => Legionary, wskazuje encję po drugiej stronie. Dlaczego funkcja, a nie sama nazwa klasy? Bo obie encje odwołują się do siebie nawzajem, a przy takim zapętleniu jedna z klas nie byłaby jeszcze zdefiniowana w chwili odczytu. Funkcja odracza to sięgnięcie do momentu, gdy obie już istnieją.
Drugi argument, (legionary) => legionary.legion, to strona odwrotna: wskazuje pole w tamtej encji, które opisuje tę samą relację. Dzięki niemu TypeORM wie, że Legion.legionaries i Legionary.legion to dwa końce jednego mostu, a nie dwie niezależne relacje.
A co dzieje się w bazie? Kolumna z identyfikatorem powstaje tylko po stronie @ManyToOne - w tabeli legionistów pojawi się legionId. Tabela legionów nie zmienia się wcale. To jest ten "numer noszony przy sobie": każdy legionista wskazuje na swój legion, a nie odwrotnie.
Wiele do wielu - legioniści i umiejętności
Drugi układ: legionista opanował wiele umiejętności, a każdą umiejętność opanowało wielu legionistów. Tu żadna ze stron nie może przechowywać identyfikatora - jedna kolumna nie pomieści listy.
@Entity()
export class Legionary {
@ManyToMany(() => Skill)
@JoinTable()
skills: Skill[];
}
@Entity()
export class Skill {
@ManyToMany(() => Legionary, (legionary) => legionary.skills)
legionaries: Legionary[];
}Rozwiązaniem jest osobna tabela pośrednia, w której jeden wiersz to jedna para: ten legionista zna tę umiejętność. Tworzy ją dla Ciebie dekorator @JoinTable() - i to jest szczegół, na którym potyka się najwięcej osób: @JoinTable() stawiamy tylko po jednej stronie, tej, którą uznajemy za właścicielkę relacji. Postawienie go po obu stronach kończy się dwiema tabelami pośrednimi opisującymi to samo. Postawienie po żadnej - błędem przy starcie aplikacji.
Zwróć uwagę, że @ManyToMany po stronie Legionary obywa się bez drugiego argumentu. Strona odwrotna jest opcjonalna: podajesz ją wtedy, gdy chcesz też z drugiej strony sięgać po powiązania - tu z umiejętności odczytać, kto ją posiadł.
Jeden do jednego - legionista i jego mapa
Trzeci układ jest najprostszy: legionista ma jedną osobistą mapę tributów, a mapa należy do jednego legionisty.
@Entity()
export class Legionary {
@OneToOne(() => TributeMap)
@JoinColumn()
map: TributeMap;
}Tu decyzję o tym, w której tabeli wyląduje kolumna z identyfikatorem, podejmujesz sam - wskazuje ją @JoinColumn(). Postawiony w encji Legionary sprawia, że to tabela legionistów dostanie kolumnę mapId. Nie myl go z @JoinTable() z poprzedniej sekcji: @JoinColumn wskazuje kolumnę w istniejącej tabeli, @JoinTable tworzy całą nową tabelę pośrednią.
Pobieranie relacji
Relacja opisana w encji nie znaczy, że dane przyjdą same. Domyślnie find() przynosi sam rekord, a pole relacji zostaje puste - i to celowo, bo inaczej pobranie jednego legionisty ciągnęłoby za sobą pół bazy. Powiązania dociągasz świadomie:
const legionaries = await this.legionaryRepo.find({
relations: ['legion', 'skills'],
});Klucz relations wylicza, co ma dojechać razem z rekordem. To jest jawne ładowanie i domyślny sposób pracy: w każdym zapytaniu decydujesz osobno, czego potrzebujesz.
Jest też wariant automatyczny. Dopisanie eager: true do relacji sprawia, że dociągnie się ona zawsze, bez proszenia:
@ManyToOne(() => Legion, (legion) => legion.legionaries, { eager: true })
legion: Legion;Wygodne - i właśnie dlatego niebezpieczne. eager działa w każdym zapytaniu o legionistów, także tam, gdzie legion jest zupełnie niepotrzebny, i po cichu obciąża zapytania w całej aplikacji. Zauważ też, czego eager nie zmienia: to nadal jedno zapytanie z JOIN-em, tylko wykonywane zawsze zamiast na żądanie. Dlatego polecam trzymać się relations i sięgać po eager wyjątkowo - gdy relacja naprawdę jest potrzebna za każdym razem.
Podsumowanie
Legion trzyma się razem, a Ty umiesz opisać jego więzy:
- relacja łączy tabele przez identyfikator, nie przez przepisywany tekst,
- dekorator opisuje stronę, na której stoi:
@OneToManypo stronie "jednego" (pole tablicowe),@ManyToOnepo stronie "wielu" (pole pojedyncze), - pierwszy argument to funkcja
() => Encja- odracza odczyt klasy, bo encje wskazują na siebie nawzajem, - drugi argument wskazuje stronę odwrotną, czyli drugi koniec tego samego mostu,
- kolumna z identyfikatorem powstaje po stronie
@ManyToOne, @ManyToManywymaga tabeli pośredniej:@JoinTable()tylko po jednej stronie,@OneToOnez@JoinColumn()decyduje, w której tabeli wyląduje kolumna -@JoinColumnwskazuje kolumnę,@JoinTabletworzy nową tabelę,- relacje pobierasz jawnie przez
relations: ['...'];eager: truerobi to zawsze i dlatego stosuj go oszczędnie.
W następnej lekcji poznasz repozytoria - archiwistów, którzy sięgają po te dane w imieniu serwisów. A na razie zapamiętaj: relacja to numer noszony przy sobie - jeden wpis w rejestrze, na który wskazują wszyscy, zamiast nazwy przepisywanej przy każdym legioniście.
Kod do tej lekcji: src/relations.ts
// Relacje w Bazie Danych - Wiezy Miedzy Legionariuszami
import {
Entity, Column, PrimaryGeneratedColumn,
OneToMany, ManyToOne, ManyToMany,
JoinColumn, JoinTable, OneToOne,
} from 'typeorm';
console.log("Relacje TypeORM - wiezi miedzy danymi imperium!");
// ===========================================
// 1. OneToMany / ManyToOne - Legion i Zolnierze
// ===========================================
@Entity('legions')
export class Legion {
@PrimaryGeneratedColumn()
id: number;
@Column()
name: string;
@Column()
commander: string;
@OneToMany(() => Soldier, soldier => soldier.legion)
soldiers: Soldier[];
}
@Entity('soldiers')
export class Soldier {
@PrimaryGeneratedColumn()
id: number;
@Column()
name: string;
@Column()
rank: string;
@ManyToOne(() => Legion, legion => legion.soldiers)
@JoinColumn({ name: 'legion_id' })
legion: Legion;
}
// ===========================================
// 2. OneToOne - Legionista i Mapa
// ===========================================
@Entity('tribute_maps')
export class TributeMap {
@PrimaryGeneratedColumn()
id: number;
@Column()
location: string;
@Column()
description: string;
@OneToOne(() => Soldier)
@JoinColumn()
owner: Soldier;
}
// ===========================================
// 3. ManyToMany - Bitwy i Legiony
// ===========================================
@Entity('battles')
export class Battle {
@PrimaryGeneratedColumn()
id: number;
@Column()
name: string;
@Column()
location: string;
@ManyToMany(() => Legion)
@JoinTable({
name: 'battle_legions',
joinColumn: { name: 'battle_id' },
inverseJoinColumn: { name: 'legion_id' },
})
legions: Legion[];
}
// ===========================================
// 4. Ladowanie relacji (eager vs lazy)
// ===========================================
// Eager loading (automatyczne):
// @OneToMany(() => Soldier, s => s.legion, { eager: true })
// soldiers: Soldier[];
// Lazy loading (na zadanie):
// const legion = await legionRepo.findOne({
// where: { id: 1 },
// relations: ['soldiers'],
// });
// Kaskadowe operacje:
// @OneToMany(() => Soldier, s => s.legion, { cascade: true })
// soldiers: Soldier[];
console.log("\n=== PODSUMOWANIE RELACJI ===");
console.log("@OneToMany + @ManyToOne - jeden do wielu (legion -> zolnierze)");
console.log("@OneToOne - jeden do jednego (legionista -> mapa)");
console.log("@ManyToMany + @JoinTable - wiele do wielu (bitwy -> legiony)");
console.log("@JoinColumn - strona posiadajaca klucz obcy");
console.log("relations: ['x'] - ladowanie relacji w zapytaniu");
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 relacja @OneToMany w TypeORM?
2. Po której stronie relacji umieszcza się @ManyToOne?
To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Napisz encje Legion z @OneToMany(() => Legionary, ...) i Legionary z @ManyToOne(() => Legion, ...)
- Układanie w poziomie
Ułóż elementy deklaracji @OneToMany w prawidłowej kolejności:
- Klikanie w kolejności
Ułóż elementy konfiguracji eager loading relacji w prawidłowej kolejności:
- Edytor kodu
Napisz encję Legionary z @ManyToMany(() => Skill) i @JoinTable() oraz encję Skill z @ManyToMany(() => Legionary)