Kurs NestJS · Moduł 1: Podstawy NestJS
Architektura NestJS - budowa Imperium
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. Z jakich elementów składa się architektura aplikacji NestJS?
2. Jaka jest główna rola kontrolera (Controller) w architekturze NestJS?
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().