Kurs NestJS · Moduł 3: TypeORM i bazy danych
PROJEKT - system inwentaryzacji tributów
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ć:
- Legionariusze - rejestracja z walidacją, rangi i uprawnienia, historia operacji każdego z nich.
- Katalog tributów - typy (złoto, srebro, klejnoty, artefakty), wycena, ocena autentyczności, historia odkrycia.
- Mapy - współrzędne geograficzne z walidacją zakresu, wskazówki poszukiwań, status odkrycia, powiązanie z konkretnym tributem.
- Transakcje i transfery - bezpieczne przeniesienie własności między legionariuszami, wymiana, pełna historia operacji.
- 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:
- Encje z relacjami - wszystkie cztery rodzaje tam, gdzie pasują, z indeksami na kolumnach, po których naprawdę filtrujesz.
- Migracje - schemat powstaje z migracji, nie z
synchronize: true. - Repozytoria z co najmniej dwoma zapytaniami napisanymi w Query Builderze.
- Transfer w transakcji, z rollbackiem sprawdzonym testem.
- Seedery idempotentne, w poprawnej kolejności.
- 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?