Kurs NestJS · Moduł 1: Podstawy NestJS

Serwisy i providery - specjaliści Imperium

5 min czytania ·
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:

  1. Dodanie @Injectable() do nowego serwisu.
  2. Import modułu z eksportowanym serwisem - jeśli pochodzi z innego modułu.
  3. Wstrzyknięcie serwisu przez konstruktor.
  4. 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, ) {},
  • private przed 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 z exports → 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) i inject (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. 1. Do czego służy dekorator @Injectable() w NestJS?

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

  1. PytanieDekorator @Injectable
  2. Ułóż w kolejnościWspółpraca serwisów
  3. Zadanie z kodemSerwis z logiką CRUD
  4. PytanieOddzielenie dostępu do danych
  5. Kliknij w kolejnościWstrzykiwanie serwisu do kontrolera
  6. Zadanie z kodemFactory Provider

Przydatne artykuły