Kurs NestJS · Moduł 2: Routing i cykl żądania
PROJEKT - skarbiec trybutów, czyli pełny cykl żądania
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:
- Kontroler z pełnym CRUD-em i parametrami trasy obsłużonymi przez
ParseIntPipe. - Middleware logujące metodę, ścieżkę i identyfikator korelacji, zarejestrowane przez
NestModule. - Dwa guardy - uwierzytelnienia i ról - z rolami zapisanymi przez
SetMetadatai odczytanymi przezReflector. - Globalny
ValidationPipez DTO dla każdego wejścia. - Interceptor ujednolicający odpowiedź i mierzący czas.
- Filtr wyjątków zwracający błędy w tym samym kształcie co odpowiedzi udane.
- 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?