Kurs NestJS · Moduł 1: Podstawy NestJS

Architektura NestJS - budowa Imperium

5 min czytania ·
W tej lekcji7

Pierwszy projekt zwykle mieści się w jednym pliku. Drugi ma ich pięć. Przy dwudziestym nikt już nie wie, gdzie leży obliczanie żołdu - w kontrolerze, w jakimś pomocniku, czy może w trzech miejscach naraz, każde nieco inaczej.

Rzym nie rozrósł się przez dosypywanie ludzi do jednej kohorty. Rozrósł się, bo każdy miał jedną rolę i wszyscy wiedzieli, która to: posłaniec nosi rozkazy, kwatermistrz liczy zapasy, pisarz prowadzi rejestr. NestJS narzuca ten sam podział - i właśnie ta narzucona struktura sprawia, że dwudziesty plik nadal da się znaleźć.

Na czym to stoi

Podstawą architektury NestJS są moduły, kontrolery i providery połączone wstrzykiwaniem zależności (Dependency Injection). Ten układ NestJS zapożyczył z Angulara - dokumentacja frameworka mówi wprost, że jego architektura jest mocno inspirowana Angularem.

Być może słyszałeś o wzorcu Model-View-Controller (MVC). NestJS potrafi w nim pracować, gdy serwer renderuje strony HTML z szablonów, ale to opcjonalna technika, a nie fundament. W typowym backendzie warstwy View w ogóle nie ma - odpowiedzią jest JSON, nie strona HTML.

Wewnątrz NestJS spotkasz też inne znane wzorce, np. każdy provider jest domyślnie singletonem - NestJS tworzy jedną jego instancję na całą aplikację. To jednak szczegół: kształt całej aplikacji wyznaczają moduły i wstrzykiwanie zależności.

Trzy role

Cała aplikacja NestJS składa się z trzech powtarzalnych elementów. Warto je zapamiętać przez pytanie, na które każdy odpowiada:

  • Kontroler - kto przyjmuje żądanie? Obsługuje żądania HTTP i zwraca odpowiedzi. Nie przechowuje danych, nie zajmuje się wyglądem, nie kompiluje niczego.
  • Serwis - jak to zrobić? Tu mieszka logika.
  • Moduł - co należy do siebie? Grupuje jedno i drugie i zgłasza NestJS.

Serwis - gdzie mieszka logika

Zacznijmy od środka, bo to serwis niesie właściwą wartość:

@Injectable()
export class LegionService {
  private legions = [
    { id: 1, name: 'Legio X Equestris' },
    { id: 2, name: 'Legio III Gallica' },
  ];

  findAll() {
    return this.legions;
  }
}

Kolejność deklaracji jest stała: @Injectable(), potem export class, dalej nazwa klasy, na końcu ciało z metodami.

I tu pada odpowiedź na pytanie, które w praktyce rozstrzyga o jakości całego projektu: logika biznesowa należy do serwisów - tego, co NestJS nazywa providerami. Nie do kontrolerów, nie do middleware, nie do plików konfiguracyjnych.

Powód jest prosty. Logika w kontrolerze jest przywiązana do HTTP - nie wywołasz jej z zadania wsadowego ani z testu jednostkowego bez udawania żądania. W middleware jest jeszcze gorzej, bo middleware pracuje na surowym żądaniu, zanim wiadomo, dokąd ono trafi. Logika w serwisie jest zwykłą metodą zwykłej klasy - wywołasz ją skąd chcesz.

Kontroler - kto przyjmuje żądanie

Kontroler bierze serwis przez konstruktor i deleguje mu pracę:

@Controller('legions')
export class LegionController {
  constructor(private readonly legionService: LegionService) {}

  @Get()
  findAll() {
    return this.legionService.findAll();
  }
}

Zwróć uwagę na proporcje. Metoda kontrolera ma jedną linię - i tak ma być. Cała jej rola to przyjąć żądanie i wskazać wykonawcę.

Kontroler nie tworzy serwisu przez new. Wpisuje go w konstruktor, a NestJS podaje gotowy - to wstrzykiwanie zależności, mechanizm, który poznasz dokładniej w kolejnych lekcjach. Na razie wystarczy widzieć skutek: kontroler mówi, czego potrzebuje, i nie martwi się, skąd to wziąć.

Moduł - co należy do siebie

Trzeci element spina dwa poprzednie:

@Module({
  controllers: [LegionController],
  providers: [LegionService],
})
export class LegionModule {}

Bez tego zgłoszenia NestJS nie wie, że te klasy istnieją - pliki same z siebie nic nie znaczą.

Zauważ, że w module widać całą prowincję naraz: kto przyjmuje żądania i kto wykonuje pracę. Otwierając nieznany projekt, moduły czyta się pierwsze, bo to one pokazują mapę.

Droga żądania

Złóżmy to w jeden przebieg. Żądanie GET /legions wędruje tak: trafia do kontrolera LegionController, ten wywołuje metodę serwisu LegionService, serwis zwraca dane, kontroler oddaje je jako odpowiedź. Moduł nie bierze udziału w locie - zadziałał wcześniej, przy starcie, gdy NestJS budował z niego mapę zależności.

Ten schemat powtarza się w całej aplikacji, niezależnie od jej wielkości. Dwudziesty zasób wygląda tak samo jak pierwszy - i dlatego wiadomo, gdzie szukać obliczania żołdu: w serwisie, zawsze w serwisie.

Podsumowanie

Imperium ma administrację, każdy zna swoją rolę:

  • podstawą architektury NestJS są moduły, kontrolery i providery połączone wstrzykiwaniem zależności - układ zapożyczony z Angulara,
  • MVC to opcjonalna technika renderowania stron z szablonów; w backendzie, który zwraca JSON, warstwy View nie ma,
  • kontroler obsługuje żądania HTTP i zwraca odpowiedzi - nie przechowuje danych ani nie zajmuje się wyglądem,
  • logika biznesowa należy do serwisów (providerów) - nie do kontrolerów, middleware ani plików konfiguracyjnych,
  • powód: logika w serwisie jest zwykłą metodą, więc wywołasz ją także poza HTTP,
  • deklaracja serwisu w kolejności: @Injectable(), export class, nazwa, ciało z metodami,
  • kontroler przyjmuje serwis przez konstruktor, nie tworzy go przez new,
  • metoda kontrolera ma zwykle jedną linię - przyjmij i deleguj,
  • moduł zgłasza kontrolery i providery; bez tego NestJS ich nie widzi,
  • droga żądania: kontroler → serwis → dane → odpowiedź; moduł działa wcześniej, przy starcie.

W następnej lekcji przyjrzymy się modułom dokładniej - zobaczysz, jak dzielą aplikację na prowincje i co decyduje o tym, że jedna widzi drugą. A na razie zapamiętaj: kontroler przyjmuje, serwis wykonuje, moduł rejestruje - i ten sam układ powtarza się w każdym zakątku aplikacji.

Kod do tej lekcji: src/imperium.module.ts
// Moduł Imperium - organizacja legionów i podatków
import { Module } from '@nestjs/common';
import { LegionController } from './legion.controller';
import { TributumController } from './tributum.controller';
import { ProvinciaController } from './provincia.controller';
import { LegionService } from './legion.service';
import { TributumService } from './tributum.service';
import { ProvinciaService } from './provincia.service';
import { AquaeductService } from './aquaeduct.service';

console.log("Loading Imperium Romanum Architecture...");

// ===========================================
// 1. Moduł Legionów - Legion Module
// ===========================================
@Module({
  controllers: [LegionController],
  providers: [LegionService],
  exports: [LegionService],
})
export class LegionModule {
  constructor() {
    console.log("Legion Module initialized - Ready to command armies!");
  }
}

// ===========================================
// 2. Moduł Podatków - Tributum Module
// ===========================================
@Module({
  imports: [LegionModule],
  controllers: [TributumController],
  providers: [TributumService],
  exports: [TributumService],
})
export class TributumModule {
  constructor() {
    console.log("Tributum Module initialized - Ready to collect taxes!");
  }
}

// ===========================================
// 3. Moduł Prowincji - Provincia Module
// ===========================================
@Module({
  imports: [LegionModule, TributumModule],
  controllers: [ProvinciaController],
  providers: [ProvinciaService, AquaeductService],
  exports: [ProvinciaService, AquaeductService],
})
export class ProvinciaModule {
  constructor() {
    console.log("Provincia Module initialized - All regions ready!");
  }
}

// ===========================================
// 4. Główny moduł aplikacji - App Module
// ===========================================
@Module({
  imports: [
    LegionModule,
    TributumModule,
    ProvinciaModule,
  ],
  controllers: [],
  providers: [
    {
      provide: 'IMPERIUM_CONFIG',
      useValue: {
        imperiumName: 'Roma Aeterna NestJS',
        caesar: 'Augustus.js',
        version: '1.0.0',
        port: 3000,
      }
    }
  ],
})
export class ImperiumAppModule {
  constructor() {
    console.log("Imperium App Module loaded successfully!");
    console.log("All systems operational - Ready for conquest!");
  }
}

// ===========================================
// 5. Demonstracja Dependency Injection
// ===========================================
export class DependencyInjectionDemo {
  static demonstrateModuleArchitecture() {
    console.log("\n=== ARCHITEKTURA MODUŁÓW ===");
    console.log("LegionModule: Zarządza legionami");
    console.log("   ├── LegionController (REST endpoints)");
    console.log("   ├── LegionService (business logic)");
    console.log("   └── exports: [LegionService]");

    console.log("\nTributumModule: Zarządza podatkami");
    console.log("   ├── imports: [LegionModule]");
    console.log("   ├── TributumController (REST endpoints)");
    console.log("   ├── TributumService (business logic)");
    console.log("   └── exports: [TributumService]");

    console.log("\nProvinciaModule: Zarządza prowincjami");
    console.log("   ├── imports: [LegionModule, TributumModule]");
    console.log("   ├── ProvinciaController (REST endpoints)");
    console.log("   ├── ProvinciaService (business logic)");
    console.log("   ├── AquaeductService (infrastructure logic)");
    console.log("   └── exports: [ProvinciaService, AquaeductService]");

    console.log("\nImperiumAppModule: Główny moduł");
    console.log("   ├── imports: [LegionModule, TributumModule, ProvinciaModule]");
    console.log("   ├── providers: [IMPERIUM_CONFIG]");
    console.log("   └── Globalne konfiguracje");
  }

  static demonstrateDependencyFlow() {
    console.log("\n=== PRZEPŁYW ZALEŻNOŚCI ===");
    console.log("1. Request → ProvinciaController");
    console.log("2. ProvinciaController → ProvinciaService (DI)");
    console.log("3. ProvinciaService → LegionService (DI via import)");
    console.log("4. ProvinciaService → TributumService (DI via import)");
    console.log("5. ProvinciaService → AquaeductService (DI)");
    console.log("6. Response ← ProvinciaController");

    console.log("\nZalety Dependency Injection:");
    console.log("   Loose coupling (luźne powiązania)");
    console.log("   Easy testing (łatwe testowanie)");
    console.log("   Code reusability (wielokrotnego użytku)");
    console.log("   Maintainability (łatwość utrzymania)");
  }
}

DependencyInjectionDemo.demonstrateModuleArchitecture();
DependencyInjectionDemo.demonstrateDependencyFlow();

export { LegionModule, TributumModule, ProvinciaModule };

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. Z jakich elementów składa się architektura aplikacji NestJS?

  2. 2. Jaka jest główna rola kontrolera (Controller) w architekturze NestJS?

  3. 3. Gdzie według architektury NestJS powinna znajdować się logika biznesowa?

Zadania praktyczne w grze

  • Edytor kodu

    Napisz serwis LegionService z dekoratorem @Injectable() i metodą findAll(), która zwraca tablicę legionistów (co najmniej jednego), np. [{ id: 1, name: 'Marcus Aurelius' }].

  • Układanie w pionie

    Ułóż elementy deklaracji serwisu NestJS w prawidłowej kolejności:

  • Edytor kodu

    Napisz kontroler LegionController z dekoratorem @Controller('legions'), który przez konstruktor przyjmuje LegionService, a w metodzie findAll() z dekoratorem @Get() zwraca wynik this.legionService.findAll().

  1. PytanieArchitektura NestJS
  2. PytanieRola kontrolera w NestJS
  3. Zadanie z kodemSerwis z logiką biznesową
  4. Ułóż w kolejnościDeklaracja serwisu NestJS
  5. PytanieLokalizacja logiki biznesowej
  6. Zadanie z kodemDependency Injection w kontrolerze

Przydatne artykuły