Kurs NestJS · Moduł 1: Podstawy NestJS

Witaj w Imperium! Wprowadzenie do NestJS

5 min czytania ·
W tej lekcji8

Salve, młody legioniście! Witaj w systemie rzymskich technologii! Jestem Konsul Caesar.js, a ty zostaniesz moim młodym legionistą w kampanii przez rozległe prowincje NestJS - najbardziej potężnego frameworka Node.js w Imperium internetu!

Podobnie jak Imperium Romanum potrzebuje solidnej konstrukcji, doświadczonego legionu i dobrze zorganizowanych kohort, tak aplikacja NestJS wymaga przemyślanej architektury, modularności i profesjonalnego podejścia do budowania skalowalnych aplikacji serwerowych.

Czym jest NestJS?

NestJS to progresywny framework Node.js do budowania wydajnych i skalowalnych aplikacji serwerowych. Został zbudowany w TypeScript i wykorzystuje najlepsze wzorce z ekosystemu JavaScript, łącząc je z mocnymi dekoratorami i systemem dependency injection znanym z Angulara.

Wyobraź sobie, że NestJS to nasze potężne Imperium Romanum:

// Nasze rzymskie kohorty (moduły)
import { Module } from '@nestjs/common';
import { LegionModule } from './legion/legion.module';
import { TributesModule } from './tributes/tributes.module';
import { ForumModule } from './forum/forum.module';

@Module({
  imports: [LegionModule, TributesModule, ForumModule],
})
export class ImperiumModule {}

Fundamenty NestJS

1. Dekoratory - nasze rzymskie oznaki rangowe

W NestJS dekoratory to jak rzymskie oznaki rangowe - oznaczają rangę i funkcję każdego elementu legionu:

// Konsul kontroluje całą operację
@Controller('consul')
export class ConsulController {
  // Obsługuje rozkazy dotyczące trybutów
  @Get('tributes')
  findTributes() {
    return 'Trybuty ze wszystkich prowincji!';
  }

  // Przyjmuje nowych legionistów
  @Post('legion')
  recruitLegionary(@Body() newLegionary: CreateLegionaryDto) {
    return 'Nowy legionista zwerbowany!';
  }
}

2. Moduły - struktury naszego Imperium

Każdy moduł to osobna struktura Imperium z określonym przeznaczeniem:

// Struktura odpowiedzialna za legion
@Module({
  controllers: [LegionController],
  providers: [LegionService],
  exports: [LegionService],
})
export class LegionModule {}

// Struktura odpowiedzialna za trybuty
@Module({
  controllers: [TributesController],
  providers: [TributesService],
  imports: [DatabaseModule],
})
export class TributesModule {}

3. Dependency Injection - łańcuch dowodzenia

System DI w NestJS to jak hierarchia w rzymskim legionie - każdy wie, od kogo ma brać rozkazy:

@Injectable()
export class TributesService {
  constructor(
    private readonly mapService: MapService,
    private readonly collectorService: CollectorService,
  ) {}

  async findTributes(province: string) {
    const location = await this.mapService.getProvince(province);
    return this.collectorService.collect(location);
  }
}

Instalacja i pierwsze kroki

Aby rozpocząć naszą kampanię w Imperium, potrzebujesz odpowiedniego wyposażenia. Podstawą jest Node.js: generator projektów nest new w NestJS 12 wymaga wersji 22.22.3 lub nowszej z linii 22 albo 24.15 lub nowszej. Sprawdzisz ją poleceniem node -v. Potem wystarczą cztery polecenia:

# Instalacja NestJS CLI - naszych inżynieryjnych narzędzi
npm install -g @nestjs/cli

# Stworzenie nowego Imperium (projektu)
nest new roman-imperium

# Wejście do systemu
cd roman-imperium

# Podniesienie sztandarów legionu (uruchomienie serwera)
npm run start:dev

Struktura rzymskiego Imperium (projektu)

roman-imperium/
├── src/
│   ├── main.ts               # Forum Romanum - punkt wejścia
│   ├── app.module.ts         # Główny Senat
│   ├── app.controller.ts     # Konsul - główny kontroler
│   ├── app.service.ts        # Primus Centurio
│   ├── legion/               # Struktura legionu
│   │   ├── legion.module.ts
│   │   ├── legion.controller.ts
│   │   └── legion.service.ts
│   ├── tributes/             # Struktura trybutów
│   └── forum/                # Struktura Forum
├── test/                     # Poligon treningowy
├── package.json              # Rejestr imperialny
└── nest-cli.json             # Instrukcje inżynieryjne

Pierwszy endpoint - sygnał imperialny

Stwórzmy nasz pierwszy endpoint, który będzie sygnalizować obecność Imperium:

// app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getSignal(): string {
    return 'Imperium gotowe do kampanii!';
  }

  @Get('status')
  getImperiumStatus() {
    return {
      legion: 'Gotowy do kampanii',
      tributes: 'Zbieranie trwa...',
      destination: 'Nowe prowincje',
      consul: 'Caesar.js do usług!',
    };
  }
}

Zalety NestJS dla Imperium

  1. Modularność - każda struktura Imperium ma swoje zadanie
  2. TypeScript - precyzja jak w rzymskim inżynierstwie
  3. Dekoratory - czytelne oznaczenia jak sygnały legionu
  4. Testowanie - sprawdzamy wszystko zanim wyruszymy na kampanię
  5. Dokumentacja - automatyczne mapy naszych prowincji (Swagger)
  6. Skalowalność - od małego castrum po architekturę Imperium

Ćwiczenie praktyczne

Czas na pierwszy test imperialny! Stwórz prosty kontroler, który będzie zarządzał podstawowymi informacjami o legionie:

// legion.controller.ts
import { Controller, Get, Post, Body } from '@nestjs/common';

@Controller('legion')
export class LegionController {
  private legionaries = [
    { name: 'Marcus Aurelius', role: 'Centurion', experience: 10 },
    { name: 'Julius Brutus', role: 'Engineer', experience: 5 },
  ];

  @Get()
  getAllLegionaries() {
    return this.legionaries;
  }

  @Post()
  addLegionary(@Body() newLegionary: any) {
    this.legionaries.push(newLegionary);
    return { message: 'Nowy legionista dołączył do legionu!', legionary: newLegionary };
  }
}

Następne kampanie

W kolejnych modułach poznamy:

  • Services i Providers - specjalistyczne role w Imperium
  • Middleware - systemy obronne
  • Guards - straże pretoriańskie
  • Interceptors - przechwytywanie sygnałów
  • Pipes - przetwarzanie danych
  • Database integration - magazyny trybutów
  • Authentication - identyfikacja obywateli Imperium
  • WebSockets - komunikacja między prowincjami
  • Testing - przygotowania przed kampanią

Przygotuj się, młody legioniście! Czeka nas fascynująca kampania przez prowincje nowoczesnego web developmentu. NestJS to nie tylko framework - to potężne narzędzie do budowania aplikacji klasy enterprise, które pomoże ci zdobyć najcenniejsze trybuty w świecie programowania!

Pamiętaj: prawdziwy legionista-programista nigdy nie wyrusza bez mapy (dokumentacji) i kompasu (najlepszych praktyk)!

Kod do tej lekcji: src/app.controller.ts
// NestJS Imperium Romanum - Pierwszy projekt
import { Controller, Get, Post, Body } from '@nestjs/common';
import { AppService } from './app.service';

console.log("Salve! Witaj w Imperium Romanum NestJS!");
console.log("Poznajemy podstawy frameworka dla prawdziwych budowniczych imperium\n");

// ===========================================
// 1. Podstawowy kontroler - Cesarz systemu
// ===========================================
console.log("=== 1. PODSTAWOWY KONTROLER ===");

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getWelcome(): string {
    return this.appService.getWelcome();
  }

  @Get('status')
  getImperiumStatus() {
    return {
      imperium: 'Roma Aeterna NestJS',
      caesar: 'Augustus.js',
      legiones: 'Gotowe do kodowania!',
      status: 'Budujemy drogi przez TypeScript',
      framework: 'NestJS',
      timestamp: new Date().toISOString(),
    };
  }
}

// ===========================================
// 2. Kontroler Legionów - Zarządzanie żołnierzami
// ===========================================
console.log("=== 2. KONTROLER LEGIONÓW ===");

interface Legionary {
  id: number;
  name: string;
  rank: string;
  experience: number;
  legio: string;
}

@Controller('legiones')
export class LegionController {
  private legionaries: Legionary[] = [
    {
      id: 1,
      name: 'Marcus Aurelius',
      rank: 'Legatus',
      experience: 10,
      legio: 'Legio X Gemina'
    },
    {
      id: 2,
      name: 'Gaius Julius',
      rank: 'Centurio',
      experience: 8,
      legio: 'Legio III Augusta'
    },
    {
      id: 3,
      name: 'Lucius Scipio',
      rank: 'Optio',
      experience: 6,
      legio: 'Legio IX Hispana'
    },
    {
      id: 4,
      name: 'Titus Flavius',
      rank: 'Miles',
      experience: 5,
      legio: 'Legio XII Fulminata'
    }
  ];

  @Get()
  getAllLegionaries(): Legionary[] {
    console.log("Lista wszystkich legionistów");
    return this.legionaries;
  }

  @Get('commanders')
  getCommanders(): Legionary[] {
    console.log("Lista dowódców");
    return this.legionaries.filter(l => l.rank === 'Legatus' || l.rank === 'Centurio');
  }

  @Post()
  recruitLegionary(@Body() newLegionary: Omit<Legionary, 'id'>): Legionary {
    const legionary: Legionary = {
      id: this.getNextId(),
      ...newLegionary,
    };

    this.legionaries.push(legionary);
    console.log(`Nowy legionista: ${legionary.name} jako ${legionary.rank}`);

    return legionary;
  }

  @Get('stats')
  getLegionStats() {
    const totalExperience = this.legionaries.reduce((sum, l) => sum + l.experience, 0);
    const avgExperience = totalExperience / this.legionaries.length;

    const rankCounts = this.legionaries.reduce((counts, l) => {
      counts[l.rank] = (counts[l.rank] || 0) + 1;
      return counts;
    }, {} as Record<string, number>);

    return {
      totalMilites: this.legionaries.length,
      totalExperience,
      averageExperience: Math.round(avgExperience * 10) / 10,
      rankDistribution: rankCounts,
      mostExperienced: this.legionaries.reduce((prev, current) =>
        prev.experience > current.experience ? prev : current
      ),
    };
  }

  private getNextId(): number {
    return Math.max(...this.legionaries.map(l => l.id), 0) + 1;
  }
}

// ===========================================
// 3. Kontroler Tributum - Zarządzanie podatkami
// ===========================================
console.log("=== 3. KONTROLER TRIBUTUM ===");

interface Tributum {
  id: number;
  name: string;
  value: number;
  provincia: string;
  collected: boolean;
  collectedBy?: string;
}

@Controller('tributum')
export class TributumController {
  private tributes: Tributum[] = [
    {
      id: 1,
      name: 'Aurum Galliae',
      value: 50000,
      provincia: 'Gallia',
      collected: true,
      collectedBy: 'Marcus Aurelius'
    },
    {
      id: 2,
      name: 'Argentum Hispaniae',
      value: 75000,
      provincia: 'Hispania',
      collected: false
    },
    {
      id: 3,
      name: 'Aes Britanniae',
      value: 100000,
      provincia: 'Britannia',
      collected: true,
      collectedBy: 'Gaius Julius'
    },
    {
      id: 4,
      name: 'Triticum Aegypti',
      value: 25000,
      provincia: 'Aegyptus',
      collected: false
    }
  ];

  @Get()
  getAllTributes(): Tributum[] {
    console.log("Lista wszystkich podatków");
    return this.tributes;
  }

  @Get('collected')
  getCollectedTributes(): Tributum[] {
    console.log("Zebrane podatki");
    return this.tributes.filter(t => t.collected);
  }

  @Get('pending')
  getPendingTributes(): Tributum[] {
    console.log("Oczekujące podatki");
    return this.tributes.filter(t => !t.collected);
  }

  @Post('collect/:id')
  collectTribute(@Body() collector: { collectedBy: string }) {
    const tributeId = 2;
    const tribute = this.tributes.find(t => t.id === tributeId);

    if (!tribute) {
      return { success: false, message: 'Tributum non inventum!' };
    }

    if (tribute.collected) {
      return { success: false, message: 'Tributum iam collectum!' };
    }

    tribute.collected = true;
    tribute.collectedBy = collector.collectedBy;

    console.log(`Podatek zebrany: ${tribute.name} przez ${collector.collectedBy}`);

    return {
      success: true,
      message: `Gratulacje! ${collector.collectedBy} zebrał ${tribute.name}!`,
      tribute,
      reward: tribute.value
    };
  }

  @Get('aerarium')
  getAerarium() {
    const collectedValue = this.tributes
      .filter(t => t.collected)
      .reduce((sum, t) => sum + t.value, 0);

    const pendingValue = this.tributes
      .filter(t => !t.collected)
      .reduce((sum, t) => sum + t.value, 0);

    return {
      aerariumValue: collectedValue,
      pendingValue,
      totalValue: collectedValue + pendingValue,
      collectionPercentage: Math.round((collectedValue / (collectedValue + pendingValue)) * 100)
    };
  }
}

// ===========================================
// 4. Demonstracja API calls
// ===========================================
console.log("=== 4. DEMONSTRACJA API ===");

class APIDemo {
  static async demonstrateAPICalls() {
    console.log("Demonstracja wywołań API:");

    console.log("GET /legiones - Pobierz legionistów:");
    const legionaries = new LegionController().getAllLegionaries();
    console.log(`Znaleziono ${legionaries.length} legionistów`);

    console.log("\nGET /legiones/stats - Statystyki legionów:");
    const stats = new LegionController().getLegionStats();
    console.log(`Łącznie milites: ${stats.totalMilites}, Śr. doświadczenie: ${stats.averageExperience}`);

    console.log("\nGET /tributum - Pobierz podatki:");
    const tributes = new TributumController().getAllTributes();
    console.log(`Znaleziono ${tributes.length} podatków`);

    console.log("\nGET /tributum/aerarium - Stan skarbca:");
    const aerarium = new TributumController().getAerarium();
    console.log(`Wartość aerarium: ${aerarium.aerariumValue} denarii (${aerarium.collectionPercentage}% zebrane)`);

    return {
      legionaries: legionaries.length,
      tributes: tributes.length,
      aerariumValue: aerarium.aerariumValue
    };
  }
}

// ===========================================
// 5. Uruchomienie demonstracji
// ===========================================
console.log("=== 5. URUCHOMIENIE APLIKACJI ===");

async function runImperiumDemo() {
  try {
    console.log("Uruchamianie Imperium Romanum NestJS Demo...");

    const results = await APIDemo.demonstrateAPICalls();

    console.log("\nPODSUMOWANIE IMPERIUM:");
    console.log(`Legioniści: ${results.legionaries} milites`);
    console.log(`Podatki: ${results.tributes} tributum`);
    console.log(`Aerarium: ${results.aerariumValue} denarii`);
    console.log("\nAplikacja NestJS gotowa do podbojów!");

    return results;
  } catch (error) {
    console.error("Błąd w Imperium:", error);
    throw error;
  }
}

runImperiumDemo().then(() => {
  console.log("\nAve Caesar! Demo ukończone pomyślnie!");
  console.log("Gratulacje - opanowałeś podstawy NestJS!");
});

export { AppController, LegionController, TributumController };

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. Czym jest NestJS?

  2. 2. W jakim języku programowania zbudowany jest NestJS?

Zadania praktyczne w grze

  • Edytor kodu

    Napisz klasę StatusController z dekoratorem @Controller('status') i metodą getStatus() z dekoratorem @Get(). Metoda ma zwracać obiekt z polem status, np. { status: 'Imperium gotowe do kampanii' }.

  • Klikanie w kolejności

    Ułóż kroki tworzenia nowego projektu NestJS w prawidłowej kolejności:

  1. PytanieCzym jest NestJS
  2. PytanieJęzyk programowania NestJS
  3. Zadanie z kodemPierwszy kontroler NestJS
  4. Kliknij w kolejnościTworzenie projektu NestJS

Przydatne artykuły