Kurs NestJS · Moduł 2: Routing i cykl żądania
Middleware - pierwszy posterunek na drodze żądania
W tej lekcji6
Trasy z poprzedniej lekcji mówią, dokąd trafi żądanie. Ta lekcja jest o tym, co dzieje się po drodze - bo między wejściem żądania do aplikacji a uruchomieniem metody kontrolera NestJS ustawia cztery posterunki: middleware, guards, interceptors i pipes. Poznasz je po kolei; zaczynamy od pierwszego.
Middleware to rogatka przy trakcie. Stoi najdalej od miasta, przepuszcza wszystkich i każdego zapisuje w rejestrze - kupca, posłańca, legionistę. Nie pyta, dokąd kto zmierza, bo na rogatce jeszcze tego nie wiadomo.
Interfejs NestMiddleware
Middleware musi implementować interfejs NestMiddleware. Nie CanActivate - to interfejs guardów z następnej lekcji; nie NestInterceptor - to interceptory; nie ExceptionFilter - ten zajmuje się błędami. Interfejs wymaga jednej metody, use, o trzech argumentach:
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
@Injectable()
export class LoggerMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
console.log(req.method, req.originalUrl);
next();
}
}Trzy argumenty to trzy role. req (Request) niesie wszystko, co przyszło od klienta: metodę HTTP, adres, nagłówki, ciało żądania. res (Response) pozwala odpowiedzieć - ustawić status, nagłówek, wysłać treść. next (NextFunction) to przepustka: wywołanie next() przekazuje żądanie dalej.
Powyższy middleware zapisuje w konsoli metodę i adres, po czym puszcza żądanie dalej. Tyle wystarczy, żeby mieć rejestr wszystkiego, co wchodzi do aplikacji.
next() - przepustka, o której łatwo zapomnieć
Wywołanie next() nie jest formalnością. Jeśli middleware nie wywoła next(), żądanie zostanie zawieszone - nie przejdzie dalej w łańcuchu. Nie zobaczysz błędu ani wyjątku: serwer się nie zrestartuje, middleware nie wykona się drugi raz, a żądanie nie przejdzie samo do kontrolera. Klient po prostu czeka, aż upłynie jego limit czasu.
To najczęstsza pomyłka przy pisaniu middleware i jedyna, która nie zostawia żadnego śladu w logach.
Czasem jednak chcemy zatrzymać żądanie - i wtedy obowiązuje jedna zasada: skoro nie przekazujesz go dalej, musisz sam zamknąć odpowiedź:
@Injectable()
export class TollMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
if (!req.headers['x-toll-paid']) {
res.status(402).json({ message: 'Myto nieopłacone' });
return;
}
next();
}
}Każda ścieżka przez metodę use musi kończyć się albo wywołaniem next(), albo odpowiedzią wysłaną przez res. Trzeciej możliwości nie ma - a raczej jest, i nazywa się zawieszonym żądaniem.
Rejestracja - cztery kroki
Sama klasa nic nie robi, dopóki nie powiesz, gdzie ma działać. Proces ma cztery kroki, w tej kolejności:
- Utworzenie klasy middleware z
@Injectable(). - Implementacja interfejsu
NestModulew klasie modułu. - Wywołanie
consumer.apply(Middleware)w metodzieconfigure(). - Określenie tras za pomocą
.forRoutes().
Krok pierwszy masz już za sobą - to klasa z poprzedniego przykładu. Pozostałe trzy dzieją się w module:
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
@Module({
controllers: [TributesController],
providers: [TributesService],
})
export class TributesModule implements NestModule {
configure(consumer: MiddlewareConsumer) {
consumer.apply(LoggerMiddleware).forRoutes('tributes');
}
}implements NestModule to obietnica, że klasa dostarczy metodę configure - NestJS wywoła ją przy budowaniu modułu. Wewnątrz consumer typu MiddlewareConsumer przyjmuje dwie informacje: .apply(LoggerMiddleware) mówi co podpiąć, .forRoutes('tributes') mówi gdzie.
Dwie rzeczy łatwo przeoczyć. Samo implements NestModule niczego nie uruchamia - to kontrakt dla TypeScriptu, który pilnuje nazwy metody i typu argumentu; NestJS wywołuje configure() w każdym module, który ją ma. Za to consumer.apply(LoggerMiddleware) bez .forRoutes() nie podpina middleware pod żadną trasę - i znowu bez żadnego błędu.
Zasięg - od jednej trasy do całej aplikacji
.forRoutes() przyjmuje kilka postaci. Napis 'tributes' obejmuje wszystkie trasy zaczynające się od /tributes. Klasa kontrolera, na przykład TributesController, obejmuje wszystkie jego trasy. Obiekt { path: 'tributes', method: RequestMethod.POST } zawęża rzecz do jednej metody HTTP. Można też wykluczać trasy przez .exclude() - przydaje się przy /health, którego nie ma sensu logować.
Gdy middleware ma obejmować całą aplikację, nie potrzebujesz modułu:
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.use(helmet());
await app.listen(3000);
}app.use() w main.ts podpina middleware globalnie i przyjmuje także zwykłe funkcje Express - dlatego tą drogą włącza się gotowe biblioteki, jak helmet czy cors. Różnica jest jedna: middleware zarejestrowane przez app.use() nie przechodzi przez wstrzykiwanie zależności, więc nie ma dostępu do serwisów aplikacji.
Gdzie kończy się middleware
Rejestr na rogatce, nagłówki CORS, parsowanie ciasteczek - to wszystko rzeczy niezależne od tego, dokąd żądanie zmierza. I dobrze, bo middleware działa na poziomie Express, zanim NestJS rozstrzygnie, który kontroler i która metoda obsłużą żądanie. Dostaje req, res i next - trzy obiekty HTTP i nic ponadto.
Decyzje w rodzaju „ten endpoint wymaga roli senatora" wymagają wiedzy, której na rogatce nie ma. Do tego służy drugi posterunek, i o nim będzie następna lekcja.
Podsumowanie
Rogatka zapisuje każdego i puszcza dalej:
- na drodze żądania stoją cztery mechanizmy: middleware → guards → interceptors → pipes; middleware jest pierwszy,
- middleware implementuje interfejs
NestMiddleware- nieCanActivate, nieNestInterceptor, nieExceptionFilter, - metoda
use(req: Request, res: Response, next: NextFunction):reqniesie żądanie,respozwala odpowiedzieć,nextprzekazuje dalej, - bez wywołania
next()żądanie zostaje zawieszone i nie przejdzie dalej w łańcuchu - serwer się nie zrestartuje, middleware nie wykona się dwa razy, żądanie nie trafi samo do kontrolera, - każda ścieżka przez
usekończy się albonext(), albo odpowiedzią wysłaną przezres, - rejestracja w czterech krokach: klasa z
@Injectable()→implements NestModulew module →consumer.apply(Middleware)wconfigure()→.forRoutes(), .forRoutes()przyjmuje ścieżkę, klasę kontrolera albo obiekt zpathimethod;.exclude()wyłącza wybrane trasy,app.use()wmain.tspodpina middleware globalnie, ale bez wstrzykiwania zależności,- middleware działa przed rozstrzygnięciem trasy docelowej, więc nadaje się do logowania i nagłówków, a nie do decyzji zależnych od endpointu.
W następnej lekcji poznasz guards - drugi posterunek, który jako pierwszy wie, dokąd żądanie zmierza, i dlatego może powiedzieć „nie". A na razie zapamiętaj jedno: middleware, które nie wywoła next(), nie zgłasza błędu. Ono po prostu milknie.
Kod do tej lekcji: src/middleware.ts
// Middleware w NestJS - Strażnicy Bram Forum
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
console.log("Middleware - strażnicy kontrolujący ruch w imperium!");
// ===========================================
// 1. Klasa middleware - Logger
// ===========================================
@Injectable()
export class RomanLoggerMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
const startTime = Date.now();
console.log('[Roman Gate] ' + req.method + ' ' + req.originalUrl);
console.log('[Roman Gate] IP: ' + req.ip);
// Po zakończeniu odpowiedzi - logujemy czas
res.on('finish', () => {
const duration = Date.now() - startTime;
console.log('[Roman Gate] Status: ' + res.statusCode + ' (' + duration + 'ms)');
});
next(); // Przekaż sterowanie dalej
}
}
// ===========================================
// 2. Middleware funkcyjne
// ===========================================
export function corsMiddleware(req: Request, res: Response, next: NextFunction) {
res.header('Access-Control-Allow-Origin', '*');
res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
res.header('X-Powered-By', 'Imperium Romanum');
console.log('[CORS] Nagłówki ustawione dla: ' + req.originalUrl);
next();
}
// ===========================================
// 3. Rejestracja middleware w module
// ===========================================
import { Module, NestModule, MiddlewareConsumer, RequestMethod } from '@nestjs/common';
@Module({
imports: [],
controllers: [],
providers: [],
})
export class AppModule implements NestModule {
configure(consumer: MiddlewareConsumer) {
// Middleware dla wszystkich tras
consumer
.apply(RomanLoggerMiddleware)
.forRoutes('*');
// Middleware tylko dla konkretnych tras
consumer
.apply(corsMiddleware)
.forRoutes(
{ path: 'legiones', method: RequestMethod.ALL },
{ path: 'tributes', method: RequestMethod.GET },
);
}
}
// ===========================================
// 4. Middleware z wykluczeniem tras
// ===========================================
// consumer
// .apply(AuthMiddleware)
// .exclude(
// { path: 'auth/login', method: RequestMethod.POST },
// { path: 'auth/register', method: RequestMethod.POST },
// )
// .forRoutes('*');
console.log("\n=== PODSUMOWANIE MIDDLEWARE ===");
console.log("Middleware działa między żądaniem a odpowiedzią");
console.log("@Injectable() + NestMiddleware - klasa middleware");
console.log("Funkcja (req, res, next) - funkcyjne middleware");
console.log("consumer.apply().forRoutes() - rejestracja w module");
console.log("next() - przekazuje sterowanie dalej");
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. Jaki interfejs musi implementować middleware w NestJS?
2. Co się stanie, jeśli middleware NIE wywoła funkcji next()?
Zadania praktyczne w grze
- Edytor kodu
Napisz LoggerMiddleware implementujący NestMiddleware z metodą use(req, res, next), która loguje metodę i URL żądania, a potem wywołuje next()
- Układanie w pionie
Uporządkuj kroki rejestracji middleware w NestJS od pierwszego do ostatniego: