Kurs NestJS · Moduł 3: TypeORM i bazy danych

Repository Pattern - organizacja skarbca

5 min czytania ·
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,
  • forRoot konfiguruje połączenie raz dla aplikacji, forFeature przydziela encje pojedynczemu modułowi,
  • find() przyjmuje opcje where, relations i order - warunki poza kluczem where są 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 - zwraca undefined, 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. 1. Jak zarejestrować repozytorium encji w module NestJS?

  2. 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

  1. PytanieRejestracja repozytorium w module
  2. Ułóż w kolejnościKonfiguracja repozytorium w NestJS
  3. Zadanie z kodemSerwis z repozytorium
  4. PytanieMetoda find z opcjami
  5. Ułóż w kolejnościWstrzyknięcie repozytorium
  6. Kliknij w kolejnościMetoda save w repozytorium
  7. Zadanie z kodemCRUD z repozytorium

Przydatne artykuły