Kurs NestJS · Moduł 1: Podstawy NestJS
PROJEKT: Rejestr Legionów Imperium
W tej lekcji8
Ave, legacie! Przez cały moduł budowałeś pojedyncze elementy: kontroler tu, serwis tam, DTO i konfigurację osobno. Prawdziwa aplikacja nie jest zbiorem luźnych klocków - to jeden organizm, w którym żądanie przechodzi przez kilka rąk, zanim wróci odpowiedź. Czas złożyć wszystko w całość: Rejestr Legionów, API, w którym kancelaria Imperium przyjmuje, sprawdza i przechowuje dane legionistów.
Co zbudujesz
REST API z pięcioma endpointami pod adresem /legionaries:
| Metoda | Adres | Co robi | Kod odpowiedzi |
|---|---|---|---|
| GET | /legionaries | lista wszystkich legionistów | 200 |
| GET | /legionaries/search?province=Gallia | legioniści z jednej prowincji | 200 |
| GET | /legionaries/:id | jeden legionista | 200 albo 404 |
| POST | /legionaries | rekrutacja nowego legionisty | 201 albo 400 |
| DELETE | /legionaries/:id | wykreślenie z rejestru | 204 albo 404 |
Każdy element tej tabeli poznałeś w tym module. Projekt sprawdza, czy umiesz je połączyć w jedną aplikację.
Etap 1: projekt i pakiety
Zacznij od nowego projektu (generator nest new w NestJS 12 potrzebuje Node.js 22.22.3+ albo 24.15+) i doinstaluj pakiety, z których korzystaliśmy w lekcjach o DTO i konfiguracji:
npm install -g @nestjs/cli
nest new legion-register
cd legion-register
npm i @nestjs/config joi class-validator class-transformer @nestjs/mapped-typesPotem utwórz w katalogu projektu plik .env. Pamiętaj, że nie trafia on do repozytorium - dopisz go do .gitignore, a obok zapisz .env.example z tymi samymi kluczami:
PORT=3000
LEGION_NAME=Legio X EquestrisEtap 2: DTO - formularz rekrutacyjny
Rejestr przyjmuje tylko kompletne zgłoszenia. Opisz je klasą DTO z dekoratorami z class-validator:
// legion/dto/create-legionary.dto.ts
import { IsEmail, IsIn, IsNotEmpty, IsString } from 'class-validator';
export class CreateLegionaryDto {
@IsString()
@IsNotEmpty()
name: string;
@IsIn(['Miles', 'Optio', 'Centurio'])
rank: string;
@IsString()
@IsNotEmpty()
province: string;
@IsEmail()
email: string;
}Same dekoratory jeszcze niczego nie blokują. Zadziałają dopiero razem z ValidationPipe, który włączysz w etapie 5.
Etap 3: serwis - kancelaria rejestru
Cała logika mieszka w serwisie. Trzyma legionistów w tablicy, nadaje im kolejne numery i zgłasza brak legionisty wyjątkiem NotFoundException. Nazwę legionu czyta z konfiguracji przez ConfigService:
// legion/legion.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { CreateLegionaryDto } from './dto/create-legionary.dto';
export interface Legionary extends CreateLegionaryDto {
id: number;
}
@Injectable()
export class LegionService {
private legionaries: Legionary[] = [];
private nextId = 1;
constructor(private readonly configService: ConfigService) {}
findAll(): Legionary[] {
return this.legionaries;
}
findByProvince(province: string): Legionary[] {
return this.legionaries.filter((l) => l.province === province);
}
findOne(id: number): Legionary {
const legionary = this.legionaries.find((l) => l.id === id);
if (!legionary) {
throw new NotFoundException('Nie ma legionisty o numerze ' + id);
}
return legionary;
}
recruit(data: CreateLegionaryDto): Legionary {
const legionary = { id: this.nextId++, ...data };
this.legionaries.push(legionary);
return legionary;
}
dismiss(id: number): void {
this.findOne(id);
this.legionaries = this.legionaries.filter((l) => l.id !== id);
}
getLegionName(): string {
return this.configService.get('LEGION_NAME');
}
}Zwróć uwagę na licznik nextId. Numer z długości tablicy powtórzyłby się po wykreśleniu kogoś ze środka rejestru, a licznik zawsze rośnie. Metoda dismiss najpierw woła findOne, więc usunięcie nieistniejącego legionisty też skończy się odpowiedzią 404.
Etap 4: kontroler - centurion przy bramie
Kontroler tylko przyjmuje żądania i przekazuje je serwisowi. Pilnuj kolejności tras: search przed :id, inaczej adres /legionaries/search trafiłby do findOne:
// legion/legion.controller.ts
import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Query } from '@nestjs/common';
import { CreateLegionaryDto } from './dto/create-legionary.dto';
import { LegionService } from './legion.service';
@Controller('legionaries')
export class LegionController {
constructor(private readonly legionService: LegionService) {}
@Get()
findAll() {
return this.legionService.findAll();
}
@Get('search')
search(@Query('province') province: string) {
return this.legionService.findByProvince(province);
}
@Get(':id')
findOne(@Param('id') id: string) {
return this.legionService.findOne(Number(id));
}
@Post()
recruit(@Body() dto: CreateLegionaryDto) {
return this.legionService.recruit(dto);
}
@Delete(':id')
@HttpCode(HttpStatus.NO_CONTENT)
dismiss(@Param('id') id: string) {
this.legionService.dismiss(Number(id));
}
}Id z adresu jest tekstem, dlatego kontroler zamienia je na liczbę przez Number(id), zanim przekaże je serwisowi. Kodu 201 dla @Post() nie trzeba ustawiać - NestJS dobiera go sam.
Etap 5: moduły i start aplikacji
Moduł legionu zgłasza kontroler i serwis:
// legion/legion.module.ts
import { Module } from '@nestjs/common';
import { LegionController } from './legion.controller';
import { LegionService } from './legion.service';
@Module({
controllers: [LegionController],
providers: [LegionService],
})
export class LegionModule {}Moduł główny wczytuje konfigurację, sprawdza ją przy starcie schematem Joi i dołącza moduł legionu:
// app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import * as Joi from 'joi';
import { LegionModule } from './legion/legion.module';
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
validationSchema: Joi.object({
PORT: Joi.number().default(3000),
LEGION_NAME: Joi.string().required(),
}),
}),
LegionModule,
],
})
export class AppModule {}Na koniec main.ts włącza walidację dla całej aplikacji i uruchamia serwer:
// main.ts
import { ValidationPipe } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
await app.listen(process.env.PORT ?? 3000);
}
bootstrap();Sprawdź rejestr
Uruchom serwer poleceniem npm run start:dev i przetestuj endpointy w drugim terminalu:
curl -X POST http://localhost:3000/legionaries \
-H "Content-Type: application/json" \
-d '{"name": "Titus Pullo", "rank": "Miles", "province": "Gallia", "email": "titus@legio.rome"}'
curl "http://localhost:3000/legionaries/search?province=Gallia"
curl http://localhost:3000/legionaries/1
curl -X DELETE http://localhost:3000/legionaries/1
curl http://localhost:3000/legionaries/1Ostatnie polecenie powinno zwrócić 404, bo legionista został wykreślony. Wyślij też zgłoszenie z błędnym adresem email albo rangą spoza listy - ValidationPipe odpowie kodem 400 i listą błędów.
Co oddajesz
Wypchnij projekt na GitHub i prześlij link w następnym zadaniu. W README opisz endpointy i sposób uruchomienia: npm install, plik .env utworzony na podstawie .env.example i npm run start:dev. Dla chętnych: dodaj PATCH /legionaries/:id z UpdateLegionaryDto opartym na PartialType, tak jak w lekcji o DTO.
Pamiętaj, legacie: w dobrze zbudowanym Imperium każdy zna swoje miejsce - kontroler przyjmuje, serwis wykonuje, DTO pilnuje bramy, a konfiguracja mieszka poza kodem.
Kod do tej lekcji: src/imperium-project.ts
// PROJEKT: Kompleksowa Aplikacja Imperium Romanum
import { Module, Controller, Injectable, Get, Post, Body, Param } from '@nestjs/common';
console.log("=== PROJEKT: Imperium Management System ===");
// ===========================================
// 1. Moduł Legionów
// ===========================================
interface Legion {
id: number;
name: string;
commander: string;
soldiers: number;
province: string;
}
@Injectable()
export class LegionService {
private legions: Legion[] = [
{ id: 1, name: 'Legio X Gemina', commander: 'Caesar', soldiers: 5000, province: 'Gallia' },
{ id: 2, name: 'Legio III Augusta', commander: 'Scipio', soldiers: 4500, province: 'Africa' },
];
findAll(): Legion[] { return this.legions; }
findById(id: number): Legion | undefined {
return this.legions.find(l => l.id === id);
}
create(data: Omit<Legion, 'id'>): Legion {
const legion = { id: this.legions.length + 1, ...data };
this.legions.push(legion);
return legion;
}
}
@Controller('legiones')
export class LegionController {
constructor(private legionService: LegionService) {}
@Get()
findAll() { return this.legionService.findAll(); }
@Get(':id')
findOne(@Param('id') id: string) { return this.legionService.findById(+id); }
}
@Module({
controllers: [LegionController],
providers: [LegionService],
exports: [LegionService],
})
export class LegionModule {}
// ===========================================
// 2. Moduł Tributów
// ===========================================
interface Tribute {
id: number;
province: string;
amount: number;
type: 'gold' | 'silver' | 'goods';
collectedAt: string;
}
@Injectable()
export class TributeService {
private tributes: Tribute[] = [
{ id: 1, province: 'Gallia', amount: 50000, type: 'gold', collectedAt: '44 BC' },
{ id: 2, province: 'Aegyptus', amount: 80000, type: 'gold', collectedAt: '30 BC' },
];
findAll() { return this.tributes; }
getTotal() { return this.tributes.reduce((sum, t) => sum + t.amount, 0); }
}
// ===========================================
// 3. Moduł Prowincji
// ===========================================
@Injectable()
export class ProvinciaService {
private provinces = [
{ name: 'Gallia', governor: 'Gaius Julius Caesar', population: 120000 },
{ name: 'Aegyptus', governor: 'Gaius Cornelius Gallus', population: 300000 },
{ name: 'Britannia', governor: 'Aulus Plautius', population: 80000 },
];
findAll() { return this.provinces; }
}
// ===========================================
// Główny moduł aplikacji
// ===========================================
@Module({
imports: [LegionModule],
providers: [TributeService, ProvinciaService],
})
export class AppModule {}
console.log("\n=== STRUKTURA PROJEKTU ===");
console.log("LegionModule - zarządzanie legionami (Controller + Service)");
console.log("TributeService - zarządzanie tributami");
console.log("ProvinciaService - zarządzanie prowincjami");
console.log("AppModule - główny moduł łączący wszystko");
console.log("\nProjekt łączy moduły, wstrzykiwanie zależności,");
console.log("kontrolery i serwisy w jedną aplikację.");
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?