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

Middleware - pierwszy posterunek na drodze żądania

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

  1. Utworzenie klasy middleware z @Injectable().
  2. Implementacja interfejsu NestModule w klasie modułu.
  3. Wywołanie consumer.apply(Middleware) w metodzie configure().
  4. 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 - nie CanActivate, nie NestInterceptor, nie ExceptionFilter,
  • metoda use(req: Request, res: Response, next: NextFunction): req niesie żądanie, res pozwala odpowiedzieć, next przekazuje 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 use kończy się albo next(), albo odpowiedzią wysłaną przez res,
  • rejestracja w czterech krokach: klasa z @Injectable() → implements NestModule w module → consumer.apply(Middleware) w configure() → .forRoutes(),
  • .forRoutes() przyjmuje ścieżkę, klasę kontrolera albo obiekt z path i method; .exclude() wyłącza wybrane trasy,
  • app.use() w main.ts podpina 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. 1. Jaki interfejs musi implementować middleware w NestJS?

  2. 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:

  1. PytanieInterfejs middleware
  2. PytanieFunkcja next() w middleware
  3. Zadanie z kodemMiddleware logujący żądania
  4. Ułóż w kolejnościRejestracja middleware w module

Przydatne artykuły