Kurs NestJS · Moduł 2: Routing i cykl żądania

PROJEKT - skarbiec trybutów, czyli pełny cykl żądania

5 min czytania ·
W tej lekcji7

Ten moduł przeszedł całą drogę, którą pokonuje żądanie: od trasy, przez middleware, guardy, interceptory i pipes, aż po filtry wyjątków i pełny cykl życia. Każdy mechanizm poznawałeś osobno. Projekt jest miejscem, w którym mają zadziałać jednocześnie - i gdzie okaże się, czy wiesz, który z nich odpowiada za co.

Zbudujesz API skarbca trybutów: rejestr kosztowności imperium, z kontrolą dostępu, walidacją i jednolitą obsługą błędów.

Miara sukcesu nie jest liczbą funkcji

Ten projekt nie ocenia się po tym, ile endpointów napisałeś. Ocenia się po jednym: czy każda odpowiedzialność trafiła do właściwego mechanizmu.

Podział jest ścisły i wynika z tego, co każdy z nich w ogóle może:

  • Middleware - logowanie, identyfikator korelacji, nagłówki CORS. Nie zna trasy docelowej, więc nie wolno mu decydować o dostępie.
  • Guard - kto ma prawo wejść. Zna handler, zwraca wartość logiczną.
  • Pipe - jeden argument metody: walidacja i transformacja.
  • Interceptor - kształt odpowiedzi i pomiar czasu; jedyny działa w obie strony.
  • Exception filter - jednolita postać błędu wychodzącego do klienta.
  • Własny dekorator - skrót na powtarzalne wyciąganie danych z kontekstu.

Dwa najczęstsze błędy wynikają z pomylenia tych ról. Autoryzacja w middleware nie może działać poprawnie, bo w tym momencie NestJS nie wie jeszcze, który endpoint obsłuży żądanie - a więc i jakiej roli wymaga. Walidacja w serwisie działa, ale jest w złym miejscu: powtarza się w każdej metodzie i wykonuje po tym, jak dane przeszły już przez pół aplikacji.

Krok 1 - trasy i kontroler

Zacznij od tego, co widać z zewnątrz:

@Controller('tributes')
export class TributesController {
  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.tributesService.findOne(id);
  }

  @Post()
  @UseGuards(AuthGuard, RolesGuard)
  @Roles('quaestor')
  create(@Body() dto: CreateTributeDto, @CurrentUser() user: User) {
    return this.tributesService.create(dto, user);
  }
}

Dwie rzeczy w tym kodzie są celowe. ParseIntPipe przy @Param gwarantuje, że do metody trafi number, więc adnotacja typu nie jest życzeniem. @CurrentUser() to twój własny dekorator - bez niego każda metoda musiałaby sięgać po request.user przez @Req(), powtarzając ten sam kod w kilkunastu miejscach.

Krok 2 - konfiguracja globalna

To, co ma obowiązywać wszędzie, rejestrujesz raz w main.ts:

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
    }),
  );

  app.useGlobalInterceptors(new TransformInterceptor());
  app.useGlobalFilters(new HttpExceptionFilter());

  await app.listen(3000);
}

Rejestracja globalna to decyzja, nie wygoda. ValidationPipe musi obowiązywać wszędzie, bo endpoint bez walidacji jest luką, a nie wyjątkiem. TransformInterceptor też - inaczej połowa API zwracałaby kopertę { success, data }, a połowa surowy obiekt, i każdy klient musiałby obsłużyć oba przypadki.

Guardów nie rejestruj globalnie w tym projekcie. Skarbiec ma endpointy publiczne (odczyt katalogu) i chronione (zapis) - a globalny guard z wyjątkami przez @Public() to rozwiązanie na większy system niż ten.

Krok 3 - guard i metadane

Kontrola dostępu opiera się na parze: dekorator zapisuje wymaganie, guard je odczytuje.

export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.get<string[]>('roles', context.getHandler());

    if (!required) {
      return true;
    }

    const { user } = context.switchToHttp().getRequest();

    return required.includes(user?.role);
  }
}

Zwróć uwagę na kolejność guardów w @UseGuards(AuthGuard, RolesGuard). Są sprawdzane od lewej, więc AuthGuard ustawia request.user, zanim RolesGuard po niego sięgnie. Odwrócenie tej pary daje guard porównujący rolę użytkownika, którego jeszcze nie ma - i odmowę dostępu dla wszystkich.

Krok 4 - interceptor i filtr wyjątków

Ostatnia para pilnuje tego, co wychodzi:

@Injectable()
export class TransformInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const start = Date.now();

    return next.handle().pipe(
      tap(() => console.log('czas:', Date.now() - start, 'ms')),
      map((data) => ({ success: true, data })),
    );
  }
}

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const response = host.switchToHttp().getResponse();
    const status = exception.getStatus();

    response.status(status).json({
      success: false,
      message: exception.message,
      timestamp: new Date().toISOString(),
    });
  }
}

Zauważ, że oba składają odpowiedź w tym samym kształcie: success plus treść. To nie przypadek - klient ma rozróżniać powodzenie od błędu jednym polem, niezależnie od tego, która ścieżka zadziałała. Rozjazd między nimi zmusza autora klienta do zgadywania.

W interceptorze tap i map stoją w jednym .pipe() i robią co innego: pierwszy podgląda wartość, żeby zmierzyć czas, drugi ją podmienia.

Kolejność, którą musisz umieć odtworzyć

Sprawdzianem zrozumienia tego modułu jest jedno pytanie: co się dzieje i w jakiej kolejności?

Middleware → guard → interceptor (przed) → pipe → handler → interceptor (po) → exception filter.

Wynikają z tego konsekwencje, które zobaczysz w swoim kodzie. Guard odrzucający żądanie sprawia, że pipe nie zwaliduje niczego, a handler się nie uruchomi - ale middleware już się wykonało i wpis w logu jest. Wyjątek rzucony przez pipe omija tap() i map() interceptora i trafia do filtra - więc czas takiego żądania nie zostanie zmierzony (chyba że interceptor ma też catchError albo finalize).

Co oddajesz

Projekt jest gotowy, gdy zawiera:

  1. Kontroler z pełnym CRUD-em i parametrami trasy obsłużonymi przez ParseIntPipe.
  2. Middleware logujące metodę, ścieżkę i identyfikator korelacji, zarejestrowane przez NestModule.
  3. Dwa guardy - uwierzytelnienia i ról - z rolami zapisanymi przez SetMetadata i odczytanymi przez Reflector.
  4. Globalny ValidationPipe z DTO dla każdego wejścia.
  5. Interceptor ujednolicający odpowiedź i mierzący czas.
  6. Filtr wyjątków zwracający błędy w tym samym kształcie co odpowiedzi udane.
  7. Własny dekorator @CurrentUser() używany zamiast @Req().

Na koniec wykonaj próbę, która sprawdza całość naraz: wyślij żądanie POST bez tokenu i z niepoprawnym ciałem jednocześnie. Musisz dostać 403, nie 400 - bo guard biegnie przed pipe'em. Jeśli dostajesz 400, twoja walidacja dzieje się za wcześnie i przecieka informacja o tym, które pola są wymagane, komuś, kto nie ma prawa wywołać tego endpointu.

Prześlij link do repozytorium, gdy skończysz.

Kod do tej lekcji: src/tribute-project.ts
// PROJEKT: System Zarządzania Trybutami Imperium
import {
  Module, Controller, Injectable, Get, Post, Put,
  Body, Param,
} from '@nestjs/common';

console.log("=== PROJEKT: ImperiumTributeVault ===");

// ===========================================
// 1. Model trybutu
// ===========================================

interface Tribute {
  id: number;
  name: string;
  province: string;
  amount: number;
  type: 'gold' | 'silver' | 'goods';
  collector: string;
  collectedAt: Date;
  verified: boolean;
}

// ===========================================
// 2. Serwis trybutów z pełnym CRUD
// ===========================================

@Injectable()
export class TributeService {
  private tributes: Tribute[] = [
    {
      id: 1, name: 'Aurum Galliae', province: 'Gallia',
      amount: 50000, type: 'gold', collector: 'Marcus',
      collectedAt: new Date(), verified: true,
    },
    {
      id: 2, name: 'Argentum Hispaniae', province: 'Hispania',
      amount: 30000, type: 'silver', collector: 'Titus',
      collectedAt: new Date(), verified: false,
    },
  ];

  findAll(filters?: { province?: string; type?: string }) {
    let result = this.tributes;
    if (filters?.province) {
      result = result.filter(t => t.province === filters.province);
    }
    if (filters?.type) {
      result = result.filter(t => t.type === filters.type);
    }
    return result;
  }

  findById(id: number) {
    return this.tributes.find(t => t.id === id);
  }

  create(data: Omit<Tribute, 'id' | 'collectedAt' | 'verified'>) {
    const tribute = {
      id: this.tributes.length + 1,
      ...data,
      collectedAt: new Date(),
      verified: false,
    };
    this.tributes.push(tribute);
    return tribute;
  }

  verify(id: number) {
    const tribute = this.findById(id);
    if (tribute) tribute.verified = true;
    return tribute;
  }

  getStatistics() {
    return {
      total: this.tributes.reduce((sum, t) => sum + t.amount, 0),
      byType: {
        gold: this.tributes.filter(t => t.type === 'gold').length,
        silver: this.tributes.filter(t => t.type === 'silver').length,
        goods: this.tributes.filter(t => t.type === 'goods').length,
      },
      verified: this.tributes.filter(t => t.verified).length,
      pending: this.tributes.filter(t => !t.verified).length,
    };
  }
}

// ===========================================
// 3. Kontroler trybutów
// ===========================================

@Controller('tributes')
export class TributeController {
  constructor(private tributeService: TributeService) {}

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

  @Get('stats')
  getStats() { return this.tributeService.getStatistics(); }

  @Get(':id')
  findOne(@Param('id') id: string) { return this.tributeService.findById(+id); }

  @Post()
  create(@Body() data: any) { return this.tributeService.create(data); }

  @Put(':id/verify')
  verify(@Param('id') id: string) { return this.tributeService.verify(+id); }
}

// ===========================================
// Moduł projektu
// ===========================================

@Module({
  controllers: [TributeController],
  providers: [TributeService],
})
export class TributeModule {}

console.log("\n=== STRUKTURA PROJEKTU ===");
console.log("TributeModule - moduł główny");
console.log("TributeService - logika biznesowa (CRUD + statystyki)");
console.log("TributeController - endpointy REST API");
console.log("\nProjekt łączy moduł, serwis i kontroler; guardy, interceptor i filtr dodasz według lekcji projektowej.");

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

  1. Projekt do wysłaniaPrześlij projekt systemu trybutów
  2. WideoPodsumowanie modułu

Przydatne artykuły