Kurs NestJS · Moduł 3: TypeORM i bazy danych

PROJEKT - system inwentaryzacji tributów

6 min czytania ·
W tej lekcji7

Osiem lekcji tego modułu przeszło drogę od pierwszego połączenia z bazą do walidacji na poziomie schematu. Projekt jest miejscem, w którym wszystko to musi zadziałać razem - i gdzie po raz pierwszy zobaczysz, że decyzje podjęte przy schemacie wracają do ciebie tydzień później, przy pisaniu zapytań.

Zbudujesz system inwentaryzacji tributów dla rzymskiego legionu: kto co posiada, skąd to pochodzi i jak przechodzi z rąk do rąk.

Dziedzina

Pięć obszarów, które system ma obsłużyć:

  1. Legionariusze - rejestracja z walidacją, rangi i uprawnienia, historia operacji każdego z nich.
  2. Katalog tributów - typy (złoto, srebro, klejnoty, artefakty), wycena, ocena autentyczności, historia odkrycia.
  3. Mapy - współrzędne geograficzne z walidacją zakresu, wskazówki poszukiwań, status odkrycia, powiązanie z konkretnym tributem.
  4. Transakcje i transfery - bezpieczne przeniesienie własności między legionariuszami, wymiana, pełna historia operacji.
  5. Legiony i kohorty - przypisanie legionariuszy, limity liczebności, centurionowie.

Nie zaczynaj od kodu. Zacznij od kartki i wypisz, co z czym jest powiązane - to jedyna decyzja w tym projekcie, której późniejsza zmiana kosztuje naprawdę dużo.

Krok 1 - schemat i relacje

Encja legionariusza pokazuje trzy rzeczy naraz: typy kolumn, indeksy i ograniczenia na poziomie bazy:

@Entity('legionaries')
@Check('tribute_count_non_negative', '"tributeCount" >= 0')
@Index(['name', 'isActive'])
export class Legionary {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 100, unique: true })
  name: string;

  @Column({ length: 50 })
  rank: string;

  @Column({ type: 'int', default: 0 })
  tributeCount: number;

  @Column({ type: 'decimal', precision: 15, scale: 2, default: 0 })
  totalTributeValue: number;

  @Column({ default: true })
  isActive: boolean;

  @CreateDateColumn()
  joinedAt: Date;

  @OneToMany(() => Tribute, (tribute) => tribute.owner)
  tributes: Tribute[];

  @ManyToOne(() => Cohort, (cohort) => cohort.legionaries)
  cohort: Cohort;
}

Trzy decyzje w tym kodzie warto rozumieć, bo będziesz je powtarzał w każdym projekcie.

Wartość tributu to decimal, nie float. Liczba zmiennoprzecinkowa nie potrafi dokładnie zapisać nawet 0,1; po tysiącu transferów sumy przestaną się zgadzać o grosze, a przy pieniądzach to koniec zaufania do systemu. precision: 15, scale: 2 znaczy: piętnaście cyfr znaczących, dwie po przecinku.

@Index(['name', 'isActive']) zakłada indeks złożony, przydatny wtedy, gdy zapytania filtrują po obu kolumnach naraz. Indeksy zakładaj po tym, jak wiesz, o co będziesz pytał - nie „na wszelki wypadek", bo każdy z nich spowalnia zapis.

@Check to ostatnia linia obrony, wpisana w samą bazę. Walidacja w DTO chroni przed złym żądaniem HTTP, ale nie przed skryptem migracyjnym, ręcznym UPDATE czy błędem w twoim własnym serwisie. Ograniczenie w bazie działa niezależnie od tego, kto pisze.

Relacje dobieraj według liczności: @OneToMany i @ManyToOne to dwie strony tej samej relacji (legionariusz ma wiele tributów, tribut ma jednego właściciela), @OneToOne pasuje do mapy przypisanej do jednego tributu, a @ManyToMany - do wymian, w których uczestniczy wielu.

Krok 2 - warstwa repozytoriów

Zapytania złożone wydzielaj do własnego repozytorium:

@Injectable()
export class TributeRepository extends Repository<Tribute> {
  async findValuableByLegionary(legionaryId: number, minValue: number) {
    return this.createQueryBuilder('tribute')
      .innerJoinAndSelect('tribute.owner', 'owner')
      .where('owner.id = :legionaryId', { legionaryId })
      .andWhere('tribute.value >= :minValue', { minValue })
      .orderBy('tribute.value', 'DESC')
      .getMany();
  }
}

Podział odpowiedzialności jest prosty: repozytorium wie, jak o coś zapytać bazę; serwis wie, kiedy i po co. Gdy w serwisie pojawia się createQueryBuilder, zwykle znaczy to, że metoda zaczęła robić dwie rzeczy naraz.

Zwróć uwagę na parametry :legionaryId i :minValue. To nie jest kwestia stylu - sklejanie zapytania z napisów otwiera drogę do wstrzyknięcia SQL. Query Builder zawsze przekazuje wartości osobno.

Krok 3 - transfer, czyli transakcja

Przeniesienie tributu to sedno tego projektu, bo składa się z operacji, które muszą wykonać się wszystkie albo żadna:

async transferTribute(tributeId: number, fromId: number, toId: number) {
  return this.dataSource.transaction(async (manager) => {
    const tribute = await manager.findOne(Tribute, {
      where: { id: tributeId, owner: { id: fromId } },
      relations: ['owner'],
    });

    if (!tribute) {
      throw new BadRequestException('Tribut nie istnieje lub nie należy do nadawcy');
    }

    tribute.owner = await manager.findOneOrFail(Legionary, { where: { id: toId } });
    await manager.save(tribute);

    await manager.decrement(Legionary, { id: fromId }, 'tributeCount', 1);
    await manager.increment(Legionary, { id: toId }, 'tributeCount', 1);

    return manager.save(Transaction, {
      tribute,
      fromLegionaryId: fromId,
      toLegionaryId: toId,
    });
  });
}

Bez transakcji awaria w połowie zostawia system w stanie niemożliwym: tribut ma nowego właściciela, ale licznik starego się nie zmniejszył - albo, gorzej, licznik spadł i wzrósł, a właściciel został ten sam. Takie rozjazdy wychodzą na jaw miesiącami później i nie da się już ustalić, które zapisy są prawdziwe.

I teraz najważniejsza pułapka całego projektu. Wewnątrz transakcji używaj wyłącznie manager, nigdy wstrzykniętego repozytorium. Wywołanie this.tributeRepository.save(...) w tym bloku sięgnie po inne połączenie - takie, które o transakcji nic nie wie. Kod skompiluje się, testy najpewniej przejdą, a przy wycofaniu zmian ta jedna operacja zostanie zapisana mimo wszystko. Reguła jest prosta: skoro jesteś w transaction(async (manager) => ...), to manager jest twoją jedyną drogą do bazy.

Krok 4 - seedery

Dane początkowe wypełniają bazę na potrzeby developmentu i testów:

export class LegionarySeeder {
  constructor(private dataSource: DataSource) {}

  async run() {
    const repo = this.dataSource.getRepository(Legionary);

    const existing = await repo.count();
    if (existing > 0) {
      return;
    }

    await repo.save([
      { name: 'Marcus Aurelius', rank: 'Centurion' },
      { name: 'Gaius Julius', rank: 'Optio' },
    ]);
  }
}

Jedno wymaganie odróżnia seeder dobry od uciążliwego: musi dać się uruchomić dwa razy. Sprawdzenie count() przed zapisem albo użycie upsert sprawia, że powtórne wywołanie niczego nie duplikuje. Bez tego każdy restart środowiska mnoży legionariuszy, a testy zaczynają zależeć od tego, ile razy ktoś wcześniej uruchomił seeder.

Kolejność też ma znaczenie: najpierw byty niezależne (legiony, kohorty), potem te, które się do nich odwołują (legionariusze), na końcu tributy i transakcje. Odwrotna kolejność kończy się błędem klucza obcego.

Walidacja na trzech poziomach

System ma trzy miejsca, w których dane mogą zostać odrzucone, i każde łapie co innego:

  • DTO z class-validator - kształt żądania HTTP. Tu odrzucisz brakującą nazwę czy ujemną wartość, zanim cokolwiek dotknie bazy.
  • Encja - unique, nullable: false, @Check. Działa niezależnie od tego, którędy dane przyszły.
  • Serwis - reguły dziedziny, których baza nie wyrazi: „nie można przekazać tributu samemu sobie", „kohorta ma limit stu ludzi".

Zdublowanie reguły w dwóch miejscach nie jest błędem - jest tanim ubezpieczeniem.

Kryteria oceny

Projekt jest gotowy, gdy spełnia sześć warunków:

  1. Encje z relacjami - wszystkie cztery rodzaje tam, gdzie pasują, z indeksami na kolumnach, po których naprawdę filtrujesz.
  2. Migracje - schemat powstaje z migracji, nie z synchronize: true.
  3. Repozytoria z co najmniej dwoma zapytaniami napisanymi w Query Builderze.
  4. Transfer w transakcji, z rollbackiem sprawdzonym testem.
  5. Seedery idempotentne, w poprawnej kolejności.
  6. Walidacja na trzech poziomach opisanych wyżej.

Zanim wyślesz, wykonaj jeden test: przerwij transfer w połowie - podaj nieistniejącego odbiorcę - i sprawdź w bazie liczniki obu legionariuszy. Jeśli którykolwiek się zmienił, gdzieś w twoim kodzie stoi wstrzyknięte repozytorium zamiast manager.

Prześlij link do repozytorium, gdy skończysz.

Kod do tej lekcji: src/tribute-inventory-project.ts
// PROJEKT: System Inwentaryzacji Tributow Rzymskich
import {
  Module, Controller, Injectable, Get, Post, Put, Delete,
  Body, Param, Query,
} from '@nestjs/common';

console.log("=== PROJEKT: System Inwentaryzacji Tributow ===");

// ===========================================
// 1. Encje projektu
// ===========================================

// Entity: Tribute
// id, name, province, amount, type, collectedBy, verified, createdAt

// Entity: Province
// id, name, governor, population, totalTribute

// Entity: Collector (ManyToOne -> Province)
// id, name, rank, assignedProvince

// Relacja: Province OneToMany -> Tribute
// Relacja: Collector ManyToOne -> Province

// ===========================================
// 2. Serwis z repozytorium i QueryBuilder
// ===========================================

@Injectable()
export class TributeInventoryService {
  private tributes = [
    { id: 1, name: 'Aurum Galliae', province: 'Gallia', amount: 50000, type: 'gold', verified: true },
    { id: 2, name: 'Argentum Hispaniae', province: 'Hispania', amount: 30000, type: 'silver', verified: false },
    { id: 3, name: 'Merces Britanniae', province: 'Britannia', amount: 15000, type: 'goods', verified: true },
    { id: 4, name: 'Aurum Aegypti', province: 'Aegyptus', amount: 80000, type: 'gold', verified: true },
  ];

  // CRUD
  findAll(filters?: { province?: string; type?: string; verified?: boolean }) {
    let result = [...this.tributes];
    if (filters?.province) result = result.filter(t => t.province === filters.province);
    if (filters?.type) result = result.filter(t => t.type === filters.type);
    if (filters?.verified !== undefined) result = result.filter(t => t.verified === filters.verified);
    return result;
  }

  findById(id: number) {
    return this.tributes.find(t => t.id === id);
  }

  create(data: any) {
    const tribute = { id: this.tributes.length + 1, verified: false, ...data };
    this.tributes.push(tribute);
    return tribute;
  }

  // Transakcja - transfer miedzy prowincjami
  async transfer(fromId: number, toProvince: string) {
    const tribute = this.findById(fromId);
    if (tribute) {
      const oldProvince = tribute.province;
      tribute.province = toProvince;
      console.log('Transfer: ' + tribute.name + ' z ' + oldProvince + ' do ' + toProvince);
    }
    return tribute;
  }

  // Statystyki (agregacja)
  getStatistics() {
    const total = this.tributes.reduce((sum, t) => sum + t.amount, 0);
    const byProvince = this.tributes.reduce((acc, t) => {
      acc[t.province] = (acc[t.province] || 0) + t.amount;
      return acc;
    }, {} as Record<string, number>);

    return { total, byProvince, count: this.tributes.length };
  }
}

// ===========================================
// 3. Kontroler z pelnym API
// ===========================================

@Controller('inventory')
export class InventoryController {
  constructor(private service: TributeInventoryService) {}

  @Get()
  findAll(@Query('province') province?: string, @Query('type') type?: string) {
    return this.service.findAll({ province, type });
  }

  @Get('stats')
  getStats() { return this.service.getStatistics(); }

  @Get(':id')
  findOne(@Param('id') id: string) { return this.service.findById(+id); }

  @Post()
  create(@Body() data: any) { return this.service.create(data); }
}

@Module({
  controllers: [InventoryController],
  providers: [TributeInventoryService],
})
export class InventoryModule {}

console.log("\n=== STRUKTURA PROJEKTU ===");
console.log("Encje z relacjami (Province, Tribute, Collector)");
console.log("Repository Pattern z CRUD");
console.log("QueryBuilder do zaawansowanych zapytan");
console.log("Transakcje do bezpiecznych transferow");
console.log("Seedery z danymi poczatkowymi");
console.log("Walidacja na wielu poziomach (DTO + DB constraints)");

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

  1. Projekt do wysłaniaPrześlij projekt systemu baz danych
  2. WideoPodsumowanie modułu

Przydatne artykuły