Kurs NestJS · Moduł 3: TypeORM i bazy danych
Repository Pattern - organizacja skarbca
W tej lekcji6
Znasz już encje i relacje - skarbiec ma spisane regały i wiadomo, co z czym się łączy. Ale kto właściwie do niego sięga? Gdyby każdy serwis w Imperium sam pisał zapytania SQL, ta sama operacja "znajdź legionistę po imieniu" powstałaby w pięciu miejscach, w pięciu wersjach, z pięcioma różnymi błędami.
Rzymianie rozwiązali to inaczej: do skarbca ma dostęp archiwista. Serwis nie schodzi do piwnicy z pochodnią - mówi archiwiście, czego szuka, a ten wie, na której półce to leży. W kodzie tym archiwistą jest repozytorium: warstwa, która oddziela logikę biznesową od sposobu, w jaki dane są przechowywane.
Trzy kroki do repozytorium
TypeORM daje repozytorium za darmo dla każdej encji - wystarczy je poprosić. Droga jest zawsze ta sama i warto ją zapamiętać jako sekwencję.
Krok pierwszy: encja. To ją poznałeś w poprzednich lekcjach - klasa z dekoratorem @Entity(), opisująca regał w skarbcu. Bez niej nie ma czego archiwizować.
Krok drugi: rejestracja w module. Mówimy NestJS, dla których encji ma przygotować archiwistów:
// legionary.module.ts
@Module({
imports: [TypeOrmModule.forFeature([Legionary])],
providers: [LegionaryService],
controllers: [LegionaryController],
})
export class LegionaryModule {}Zwróć uwagę na nazwę: forFeature, nie forRoot. Ta różnica jest częstym źródłem pomyłek, więc rozdzielmy je raz na zawsze. forRoot wywołujesz raz, w module głównym - konfiguruje połączenie z bazą dla całej aplikacji. forFeature wywołujesz w każdym module z osobna i wyliczasz w nim tylko te encje, których ten moduł faktycznie używa. Jeden ustawia drogę do skarbca, drugi przydziela archiwistów konkretnej kohorcie.
Krok trzeci: wstrzyknięcie do serwisu. Zarejestrowanego archiwistę odbieramy w konstruktorze:
@Injectable()
export class LegionaryService {
constructor(
@InjectRepository(Legionary)
private legionaryRepo: Repository<Legionary>,
) {}
}Dekorator @InjectRepository(Legionary) mówi NestJS, o którego archiwistę prosimy - bo w aplikacji jest ich wielu, po jednym na encję. Typ Repository<Legionary> to zapis generyczny: Repository to ogólny rodzaj archiwisty, a <Legionary> zawęża go do tej jednej encji. Dzięki temu TypeScript wie, że find() zwróci legionistów, a nie cokolwiek - i podpowie Ci pola przy pisaniu kodu.
Zapamiętaj tę kolejność: encja, forFeature w module, @InjectRepository w serwisie. Pominięcie środkowego kroku daje przy starcie aplikacji błąd o nieznanym providerze - i to najczęstsza przyczyna tego komunikatu.
Odczyt - find z opcjami
Archiwista przyjmuje polecenia w postaci obiektu opcji. Najważniejszy klucz to where:
async findAll(): Promise<Legionary[]> {
return this.legionaryRepo.find();
}
async findCenturions(): Promise<Legionary[]> {
return this.legionaryRepo.find({
where: { rank: 'Centurion' },
relations: ['centurion'],
order: { name: 'ASC' },
});
}find() bez argumentów przynosi wszystko. Z obiektem opcji - zawęża. Uwaga na jeden szczegół, na którym potyka się wielu: warunki muszą siedzieć w kluczu where. Zapis find({ rank: 'Centurion' }) nie jest filtrem - to nieznana opcja, którą TypeORM zignoruje, i dostaniesz wszystkich legionistów zamiast samych centurionów. Błąd nie zostanie zgłoszony, więc łatwo go przeoczyć.
Klucz relations dociąga powiązane encje - to repozytoryjny odpowiednik leftJoinAndSelect z Query Buildera. order sortuje. Gdy potrzebujesz jednego rekordu, wołasz findOne({ where: { id } }) - zwróci encję albo null, jeśli nic nie pasuje.
Zapis - create i save
Tworzenie nowego legionisty to para metod, i warto rozumieć, dlaczego dwie, a nie jedna:
async create(dto: CreateLegionaryDto): Promise<Legionary> {
const legionary = this.legionaryRepo.create(dto);
return this.legionaryRepo.save(legionary);
}create() nie dotyka bazy. Buduje tylko obiekt encji w pamięci - przepisuje pola z DTO i nadaje mu klasę Legionary, dzięki czemu zadziałają dekoratory, hooki i wartości domyślne. Dopiero save() wysyła go do skarbca i zwraca zapisaną encję, już z nadanym przez bazę id.
Ten podział ma sens praktyczny: między create a save możesz jeszcze coś zmienić albo sprawdzić. save() ma też drugą twarz - wywołany na encji, która ma już id, wykona aktualizację zamiast wstawienia. Jedna metoda, dwa zachowania, zależnie od tego, czy rekord istnieje.
Aktualizacja - preload
Do zmiany istniejącego rekordu służy preload, metoda o nieoczywistej nazwie:
async update(id: number, dto: UpdateLegionaryDto): Promise<Legionary> {
const legionary = await this.legionaryRepo.preload({ id, ...dto });
if (!legionary) {
throw new NotFoundException(`Legionista ${id} nie istnieje`);
}
return this.legionaryRepo.save(legionary);
}preload pobiera z bazy rekord o podanym id, nakłada na niego pola z DTO i zwraca gotową do zapisania encję - ale jeszcze nic nie zapisuje. Zaletą jest to, czego nie musisz robić: pola nieobecne w DTO zachowają swoje dotychczasowe wartości, więc częściowa aktualizacja nie wyzeruje reszty rekordu. Gdy rekordu o takim id nie ma, preload zwraca undefined - stąd sprawdzenie przed zapisem. Dopiero save() utrwala zmianę.
Usuwanie - remove i delete
Na koniec dwie metody usuwania, które robią to samo w różny sposób:
async remove(id: number): Promise<void> {
const legionary = await this.legionaryRepo.findOne({ where: { id } });
if (!legionary) {
throw new NotFoundException(`Legionista ${id} nie istnieje`);
}
await this.legionaryRepo.remove(legionary);
}remove() przyjmuje encję - dlatego najpierw ją pobieramy. Kosztuje to dodatkowe zapytanie, ale w zamian dostajesz pewność, że rekord istniał, i uruchamiasz hooki usuwania. delete(id) przyjmuje samo id i kasuje jednym zapytaniem - szybciej, ale bez sprawdzenia i bez hooków. Wybierz świadomie: remove tam, gdzie liczy się poprawność i reakcja na brak rekordu, delete tam, gdzie liczy się szybkość.
Podsumowanie
Skarbiec ma archiwistę i nikt nie schodzi do piwnicy na własną rękę:
- repozytorium oddziela logikę biznesową od sposobu przechowywania danych,
- droga jest zawsze trzystopniowa: encja z
@Entity(),TypeOrmModule.forFeature([Encja])w module,@InjectRepository(Encja)w konstruktorze serwisu, forRootkonfiguruje połączenie raz dla aplikacji,forFeatureprzydziela encje pojedynczemu modułowi,find()przyjmuje opcjewhere,relationsiorder- warunki poza kluczemwheresą po cichu ignorowane,create()buduje encję w pamięci,save()zapisuje ją do bazy i potrafi też aktualizować,preload()scala istniejący rekord ze zmianami, nie zapisując - zwracaundefined, gdy rekordu nie ma,remove(encja)usuwa bezpieczniej i z hookami,delete(id)szybciej i bez nich.
W następnej lekcji poznasz Query Builder - narzędzie na pytania, których archiwista nie potrafi obsłużyć samym find(). A na razie zapamiętaj: repozytorium to archiwista skarbca - serwis mówi, czego potrzebuje, a nie jak to wyjąć z półki.
Kod do tej lekcji: src/repository-pattern.ts
// Repository Pattern - Organizacja Skarbca
import { Injectable, NotFoundException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
console.log("Repository Pattern - zarzadca dostepu do danych!");
// ===========================================
// 1. Podstawowy serwis z repozytorium
// ===========================================
// Zakladamy encje Legionary z poprzedniej lekcji
@Injectable()
export class LegionaryService {
constructor(
@InjectRepository('Legionary')
private legionaryRepo: Repository<any>,
) {}
// Pobierz wszystkich
async findAll() {
return this.legionaryRepo.find();
}
// Pobierz po ID
async findById(id: number) {
const legionary = await this.legionaryRepo.findOneBy({ id });
if (!legionary) {
throw new NotFoundException('Legionary non inventus!');
}
return legionary;
}
// Utworz nowego
async create(data: any) {
const legionary = this.legionaryRepo.create(data);
return this.legionaryRepo.save(legionary);
}
// Zaktualizuj
async update(id: number, data: any) {
const legionary = await this.findById(id);
Object.assign(legionary, data);
return this.legionaryRepo.save(legionary);
}
// Usun
async remove(id: number) {
const result = await this.legionaryRepo.delete(id);
if (result.affected === 0) {
throw new NotFoundException('Legionary non inventus!');
}
}
// Znajdz po rangu
async findByRank(rank: string) {
return this.legionaryRepo.find({ where: { rank } });
}
// Zlicz legionistow w legionie
async countByLegion(legionName: string) {
return this.legionaryRepo.count({
where: { legion: legionName },
});
}
}
// ===========================================
// 2. CRUD serwis z garnizonem
// ===========================================
@Injectable()
export class GarrisonService {
constructor(
@InjectRepository('Garrison')
private garrisonRepo: Repository<any>,
) {}
async findAll() {
return this.garrisonRepo.find({
order: { soldiers: 'DESC' },
});
}
async create(data: any) {
return this.garrisonRepo.save(data);
}
async update(id: number, data: any) {
await this.garrisonRepo.update(id, data);
return this.garrisonRepo.findOneBy({ id });
}
async remove(id: number) {
await this.garrisonRepo.delete(id);
}
}
// ===========================================
// Rejestracja w module
// ===========================================
// @Module({
// imports: [TypeOrmModule.forFeature([Legionary, Garrison])],
// providers: [LegionaryService, GarrisonService],
// exports: [LegionaryService],
// })
// export class LegionaryModule {}
console.log("\n=== PODSUMOWANIE REPOSITORY ===");
console.log("@InjectRepository(Entity) - wstrzyknij repozytorium");
console.log("repo.find() - pobierz wszystkie rekordy");
console.log("repo.findOneBy() - pobierz jeden rekord");
console.log("repo.save() - zapisz (insert lub update)");
console.log("repo.delete() - usun rekord");
console.log("repo.count() - zlicz rekordy");
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 zarejestrować repozytorium encji w module NestJS?
2. Jak znaleźć wszystkich legionistów z rangą 'Centurion' używając repozytorium TypeORM?
Zadania praktyczne w grze
- Układanie w pionie
Uporządkuj kroki konfiguracji repozytorium TypeORM w module NestJS:
- Edytor kodu
Napisz LegionaryService z @InjectRepository(Legionary) i metodami findAll(), findOne(id), create(dto) i remove(id)
- Układanie w poziomie
Ułóż elementy wstrzyknięcia repozytorium w konstruktorze serwisu:
- Klikanie w kolejności
Ułóż elementy zapisywania nowej encji przez repozytorium:
- Edytor kodu
Napisz serwis z metodami: find() z where i relations, create() z save, update() z preload i save, delete() z remove