Kurs NestJS · Moduł 1: Podstawy NestJS
Serwisy i providery - specjaliści Imperium
W tej lekcji6
Centurion z poprzedniej lekcji przyjmuje rozkazy i przekazuje je dalej. Ale komu? Gdyby sam liczył żołd, sprawdzał zapasy i pisał do skarbca, przestałby być centurionem, a stałby się jednoosobową kohortą - i tę samą pracę trzeba by powtórzyć w każdym innym oddziale.
Legion ma na to specjalistów: kowala, medyka, kwatermistrza. Każdy zna jedną rzecz i robi ją dla wszystkich. W NestJS takim specjalistą jest serwis.
Dekorator, który czyni specjalistę
Serwis to zwykła klasa z jednym dekoratorem:
@Injectable()
export class LegionService {
private legions: Legion[] = [];
private nextId = 1;
findAll(): Legion[] {
return this.legions;
}
findById(id: number): Legion {
return this.legions.find((legion) => legion.id === id);
}
recruit(data: CreateLegionDto): Legion {
const legion = { id: this.nextId++, ...data };
this.legions.push(legion);
return legion;
}
dismiss(id: number): void {
this.legions = this.legions.filter((legion) => legion.id !== id);
}
}@Injectable() oznacza klasę jako provider, który może być wstrzykiwany. To jedyne, co robi - i warto to odgraniczyć od sąsiadów, bo dekoratory w NestJS wyglądają podobnie: kontroler oznacza @Controller(), moduł @Module(), a middleware to klasa implementująca NestMiddleware. @Injectable() nie czyni z klasy żadnego z nich - mówi tylko, że NestJS ma umieć ją komuś podać.
Cztery metody powyżej to typowy zestaw: findAll() zwraca wszystko, findById(id) jedną pozycję, recruit(data) tworzy nową, dismiss(id) usuwa. Nazwy opisują czynność w dziedzinie, nie czasownik HTTP - bo serwis nie wie, że istnieje jakiś HTTP.
Wstrzyknięcie do kontrolera
Gotowego specjalistę kontroler dostaje przez konstruktor:
@Controller('legions')
export class LegionController {
constructor(private readonly legionService: LegionService) {}
@Get()
findAll() {
return this.legionService.findAll();
}
}Kolejność zapisu jest stała: constructor(, potem private readonly legionService: , dalej LegionService, na końcu ) {}.
Ten skrót zasługuje na wyjaśnienie, bo wygląda dziwnie. Słowo private przed parametrem konstruktora to skrót TypeScriptu: deklaruje pole klasy i przypisuje mu wartość w jednym miejscu. Bez niego musiałbyś napisać private legionService: LegionService osobno i this.legionService = legionService w ciele konstruktora. readonly dokłada gwarancję, że nikt tego pola później nie podmieni.
Sam nie tworzysz instancji przez new - robi to NestJS. Patrzy na typ parametru, znajduje pasujący provider i podaje go gotowego. To jest wstrzykiwanie zależności: klasa mówi, czego potrzebuje, a nie skąd to wziąć.
Serwis w serwisie
Specjaliści korzystają nawzajem ze swoich usług tak samo. Droga ma cztery kroki i warto ją znać w kolejności:
- Dodanie
@Injectable()do nowego serwisu. - Import modułu z eksportowanym serwisem - jeśli pochodzi z innego modułu.
- Wstrzyknięcie serwisu przez konstruktor.
- Wywołanie metody wstrzykniętego serwisu.
@Injectable()
export class PayrollService {
constructor(private readonly legionService: LegionService) {}
calculateTotalPay(): number {
const legions = this.legionService.findAll();
return legions.reduce((sum, legion) => sum + legion.pay, 0);
}
}Krok drugi jest tym, o którym najczęściej się zapomina. Provider zadeklarowany w module nie jest automatycznie widoczny gdzie indziej - musi być wypisany w exports swojego modułu, a moduł, który go potrzebuje, musi go zaimportować. Pominięcie tego daje przy starcie błąd o nierozwiązanej zależności.
Oddzielenie dostępu do danych
Nasz LegionService trzyma dane w tablicy. Gdy przyjdzie prawdziwa baza, każda metoda będzie musiała się zmienić - a razem z nią wszystko, co jej używa.
Rozwiązaniem jest Repository Pattern - wzorzec, który oddziela logikę dostępu do danych od logiki biznesowej. Serwis mówi wtedy, co chce zrobić, a repozytorium wie, jak dane pobrać. Zmiana tablicy na bazę dotyka wyłącznie repozytorium.
Nie myl go z innymi wzorcami o podobnie brzmiących nazwach: Singleton pilnuje, by istniała jedna instancja, Observer rozsyła powiadomienia o zdarzeniach, Proxy podstawia zastępczy obiekt w miejsce prawdziwego. Tylko Repository dotyczy rozdzielenia danych od logiki.
Provider z fabryki
Zwykle wystarczy podać klasę i NestJS sam ją utworzy. Czasem jednak instancja zależy od czegoś, co znasz dopiero przy starcie - wtedy podajesz przepis zamiast klasy:
@Module({
providers: [
{
provide: 'STORAGE_SERVICE',
useFactory: (config: ConfigService) => {
return config.get('STORAGE') === 'cloud'
? new CloudStorageService()
: new LocalStorageService();
},
inject: [ConfigService],
},
],
})
export class StorageModule {}Trzy pola opisują ten przepis. provide to nazwa, pod którą provider będzie dostępny. useFactory to funkcja tworząca instancję - tu wybiera między dwiema implementacjami zależnie od konfiguracji. inject wylicza, czego potrzebuje sama fabryka; NestJS poda jej to jako argumenty, w tej samej kolejności.
Zauważ, po co to całe zamieszanie: reszta aplikacji prosi o 'STORAGE_SERVICE' i nie wie, którą implementację dostała. Podmiana chmury na dysk lokalny to zmiana w jednym miejscu - a nie w każdym serwisie, który zapisuje pliki.
Podsumowanie
Specjaliści na miejscu, każdy zna swoją rzecz:
- serwis trzyma logikę, kontroler tylko kieruje żądania,
@Injectable()oznacza klasę jako provider, który może być wstrzykiwany - nie czyni jej kontrolerem, modułem ani middleware,- nazwy metod opisują czynność w dziedzinie (
findAll,findById,recruit,dismiss), nie czasowniki HTTP, - wstrzyknięcie w kolejności:
constructor(,private readonly nazwa:,TypSerwisu,) {}, privateprzed parametrem konstruktora deklaruje pole i przypisuje wartość w jednym miejscu,- instancji nie tworzysz przez
new- NestJS dobiera provider po typie, - serwis w serwisie:
@Injectable()→ import modułu zexports→ wstrzyknięcie przez konstruktor → wywołanie metody, - provider nie jest widoczny poza swoim modułem, dopóki nie trafi do
exports, - Repository Pattern oddziela logikę dostępu do danych od logiki biznesowej - Singleton, Observer i Proxy rozwiązują zupełnie inne problemy,
- provider z fabryki opisują
provide(nazwa),useFactory(funkcja tworząca) iinject(zależności fabryki), - dzięki fabryce reszta aplikacji nie wie, którą implementację dostała.
W następnej lekcji zbudujesz z tych elementów pierwsze REST API - komplet operacji CRUD na jednym zasobie. A na razie zapamiętaj: kontroler wie kto ma coś zrobić, serwis wie jak - i tylko dzięki temu tę samą wiedzę wywołasz z dowolnego miejsca aplikacji.
Kod do tej lekcji: src/legion.service.ts
// Serwisy i Providers - Specjaliści w Imperium
import { Injectable, NotFoundException } from '@nestjs/common';
console.log("Serwisy NestJS - specjaliści wykonujący prawdziwą pracę!");
// ===========================================
// 1. Podstawowy serwis z @Injectable
// ===========================================
interface Legionary {
id: number;
name: string;
rank: string;
experience: number;
legion: string;
}
@Injectable()
export class LegionService {
private legionaries: Legionary[] = [
{ id: 1, name: 'Marcus Aurelius', rank: 'Centurio', experience: 10, legion: 'Legio X' },
{ id: 2, name: 'Julia Domna', rank: 'Optio', experience: 8, legion: 'Legio X' },
{ id: 3, name: 'Titus Flavius', rank: 'Miles', experience: 3, legion: 'Legio III' },
];
findAll(): Legionary[] {
return this.legionaries;
}
findById(id: number): Legionary {
const legionary = this.legionaries.find(l => l.id === id);
if (!legionary) {
throw new NotFoundException('Legionary non inventus!');
}
return legionary;
}
create(data: Omit<Legionary, 'id'>): Legionary {
const newLegionary: Legionary = {
id: Math.max(...this.legionaries.map(l => l.id)) + 1,
...data,
};
this.legionaries.push(newLegionary);
return newLegionary;
}
update(id: number, data: Partial<Legionary>): Legionary {
const legionary = this.findById(id);
Object.assign(legionary, data);
return legionary;
}
remove(id: number): void {
const index = this.legionaries.findIndex(l => l.id === id);
if (index === -1) throw new NotFoundException('Legionary non inventus!');
this.legionaries.splice(index, 1);
}
// Logika biznesowa - obliczanie siły legionu
calculateLegionStrength(legionName: string): number {
const soldiers = this.legionaries.filter(l => l.legion === legionName);
return soldiers.reduce((sum, s) => sum + s.experience * 10, 0);
}
}
// ===========================================
// 2. Serwis z wstrzykniętym innym serwisem
// ===========================================
@Injectable()
export class RankService {
private rankHierarchy: Record<string, number> = {
Miles: 1,
Optio: 2,
Centurio: 3,
Tribunus: 4,
Legatus: 5,
};
getRankLevel(rank: string): number {
return this.rankHierarchy[rank] || 0;
}
canPromote(currentRank: string, targetRank: string): boolean {
return this.getRankLevel(targetRank) === this.getRankLevel(currentRank) + 1;
}
}
@Injectable()
export class PromotionService {
constructor(
private readonly legionService: LegionService,
private readonly rankService: RankService,
) {}
promote(legionaryId: number, newRank: string): Legionary {
const legionary = this.legionService.findById(legionaryId);
if (!this.rankService.canPromote(legionary.rank, newRank)) {
throw new Error('Awans niemożliwy - niewłaściwa ranga!');
}
return this.legionService.update(legionaryId, { rank: newRank });
}
}
console.log("\n=== PODSUMOWANIE SERWISÓW ===");
console.log("@Injectable() - oznacza klasę jako provider");
console.log("Serwisy zawierają logikę biznesową");
console.log("DI pozwala wstrzykiwać serwisy do siebie nawzajem");
console.log("Kontrolery delegują pracę do serwisów");
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Do czego służy dekorator @Injectable() w NestJS?
2. Jaki wzorzec projektowy oddziela logikę dostępu do danych od logiki biznesowej?
Zadania praktyczne w grze
- Układanie w pionie
Uporządkuj kroki tworzenia serwisu współpracującego z innym serwisem:
- Edytor kodu
Napisz serwis LegionService z prywatną tablicą legionistów i metodami: findAll() zwraca tablicę, findById(id) zwraca legionistę o tym id (albo undefined), recruit(data) dodaje legionistę z nowym, niepowtarzalnym id i go zwraca, dismiss(id) usuwa legionistę o tym id.
- Klikanie w kolejności
Ułóż elementy wstrzykiwania serwisu przez konstruktor kontrolera:
- Edytor kodu
Zdefiniuj stałą storageProvider z provide: 'STORAGE_SERVICE', inject: [ConfigService] i useFactory, która dostaje ConfigService i zwraca new CloudStorageService(), gdy config.get('STORAGE') === 'cloud', a w przeciwnym razie new LocalStorageService(). Obie klasy napisz sam, a storageProvider dodaj do providers modułu StorageModule.