Kurs NestJS · Moduł 1: Podstawy NestJS

PROJEKT: Rejestr Legionów Imperium

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

MetodaAdresCo robiKod odpowiedzi
GET/legionarieslista wszystkich legionistów200
GET/legionaries/search?province=Gallialegioniści z jednej prowincji200
GET/legionaries/:idjeden legionista200 albo 404
POST/legionariesrekrutacja nowego legionisty201 albo 400
DELETE/legionaries/:idwykreślenie z rejestru204 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-types

Potem 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 Equestris

Etap 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/1

Ostatnie 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?

  1. Projekt do wysłaniaPrześlij projekt Imperium NestJS
  2. WideoPodsumowanie modułu

Przydatne artykuły