Skip to content

7. Der Lebenszyklus einer Anfrage

Zwischen dem Eintreffen einer Anfrage und der Ausführung der Action sind in [NestJS] mehrere Arten von Objekten beteiligt, jede mit einer bestimmten Rolle. Einigen sind wir bereits begegnet: Middleware ([res.locals], [cookie-parser]) und Pipes ([ParseIntPipe], [ValidationPipe]). Die Fallstudie verwendet alle fünf:

Image

Objekt
Rolle
In der Fallstudie
Middleware
bereitet die Anfrage vor; kennt die Action noch nicht
Lesen der Cookies, der Sprache, der Flash-Nachricht
Guard
erlaubt oder verweigert den Zugriff auf die Action
Authentifizierung (JWT), Rollen
Interceptor
Code vor und nach der Action
der angemeldete Benutzer, den Views zur Verfügung gestellt
Pipe
konvertiert und validiert einen Parameter
[ParseIntPipe]
Exception-Filter
wandelt eine Exception in eine Antwort um
HTML-Fehlerseiten, Umleitung auf /login

7.1. Beispiel 24: Die fünf Schritte

Beispiel 24 enthält eine Action, die das Quadrat einer Zahl berechnet, und je ein Objekt jeder Art. Jedes schreibt eine Zeile in die Konsole, sodass wir die Reihenfolge ihrer Ausführung sehen können.

Die Datei [src/logger.middleware.ts]:

import { Injectable, NestMiddleware } from '@nestjs/common';
import { NextFunction, Request, Response } from 'express';

// 1. die MIDDLEWARE: die Erste, die die Anfrage sieht. Sie weiß noch nicht,
//    welche Action sie bearbeiten wird
@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction): void {
    console.log(`\n--- ${req.method} ${req.originalUrl}`);
    console.log('1. middleware');
    next(); // wir übergeben an den Rest der Kette
  }
}
  • Zeile 7: Eine [NestJS] -Middleware ist eine Klasse, die [NestMiddleware] implementiert. Eine einfache Funktion wie in den vorherigen Beispielen würde ebenfalls funktionieren;
  • Zeile 11: Die Middleware muss [next()] aufrufen, um die Kontrolle an den nächsten Schritt zu übergeben (oder selbst eine Antwort zu senden). Andernfalls bleibt die Anfrage blockiert.

Die Datei [src/app.module.ts]:

import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
import { CalcController } from './calc.controller';
import { LoggerMiddleware } from './logger.middleware';

@Module({
  controllers: [CalcController],
})
export class AppModule implements NestModule {
  // eine Klassen-Middleware wird im Modul registriert
  configure(consumer: MiddlewareConsumer): void {
    consumer.apply(LoggerMiddleware).forRoutes('*');
  }
}

Zeilen 10–12: Eine klassenbasierte Middleware registriert sich in einem Modul, das [NestModule] implementiert. [forRoutes('*')] wendet sie auf alle Routen an.

Die Datei [src/block.guard.ts]:

import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { Request } from 'express';

// 2. der GUARD: entscheidet, ob die Anfrage die Action erreichen darf.
//    false -> NestJS wirft eine ForbiddenException (403)
@Injectable()
export class BlockGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const req = context.switchToHttp().getRequest<Request>();
    // der Guard kennt die anvisierte Action (die Middleware nicht)
    console.log(`2. guard (targeted action: ${context.getHandler().name})`);
    return req.query.block !== '1';
  }
}
  • Zeile 7: Ein Guard implementiert [CanActivate];
  • Zeile 8: Seine Methode [canActivate] erhält den Ausführungskontext und liefert [true] (die Anfrage wird fortgesetzt) oder [false] ([NestJS] löst eine [ForbiddenException] aus, Code 403);
  • Zeile 11: Anders als die Middleware kennt der Guard die Ziel-Action ([getHandler()]) und ihren Controller ([getClass()]). Dadurch kann ein Guard die auf die Action angewandten Dekoratoren lesen (siehe [@Roles], im nächsten Kapitel).

Die Datei [src/timing.interceptor.ts]:

import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Observable, tap } from 'rxjs';

// 3. der INTERCEPTOR: Code VOR der Action und NACH ihr
@Injectable()
export class TimingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
    console.log('3. interceptor (before)');
    const start = Date.now();
    // next.handle() führt aus, was folgt: Pipes, dann Action. Das Ergebnis
    // der Action kommt im zurückgegebenen Stream (Observable) an
    return next.handle().pipe(tap(() => console.log(`6. interceptor (after, ${Date.now() - start} ms)`)));
  }
}
  • Zeile 6: Ein Interceptor implementiert [NestInterceptor];
  • Zeile 8: Der Code vor [next.handle()] wird vor der Action ausgeführt;
  • Zeile 12: [next.handle()] führt den Rest aus (Pipes, gefolgt von der Action) und liefert einen [RxJS] -Stream ([Observable]), der das Ergebnis der Action erzeugen wird. Der Operator [tap] führt Code nach der Action aus, ohne deren Ergebnis zu verändern (der Operator [map] würde dies erlauben).

Die Datei [src/integer.pipe.ts]:

import { BadRequestException, Injectable, PipeTransform } from '@nestjs/common';

// 4. die PIPE: konvertiert und validiert einen Parameter der Action
@Injectable()
export class IntegerPipe implements PipeTransform<string, number> {
  transform(value: string): number {
    console.log(`4. pipe (received value: "${value}")`);
    const n = Number(value);
    if (!Number.isInteger(n)) {
      throw new BadRequestException(`"${value}" is not an integer`);
    }
    return n;
  }
}

Eine Pipe ähnlich [ParseIntPipe] (siehe Beispiel 12).

Die Datei [src/error-page.filter.ts]:

import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus } from '@nestjs/common';
import { Response } from 'express';

// x. der EXCEPTION-FILTER: empfängt jede unbehandelte Exception, woher
//    sie auch kommt (Guard, Pipe, Action ...), und erzeugt die Antwort.
//    @Catch() ohne Argument: alle Exceptions
@Catch()
export class ErrorPageFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost): void {
    const res = host.switchToHttp().getResponse<Response>();
    const status = exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
    const message = exception instanceof HttpException ? exception.message : 'Internal error';
    console.log(`x. exception filter (${status}: ${message})`);
    // eine HTML-Seite statt der standardmäßigen JSON-Antwort von NestJS
    res.status(status).render('error', { status, message });
  }
}
  • Zeile 7: [@Catch()] ohne Argument: Der Filter erhält alle Exceptions. [@Catch(HttpException)] würde ihn auf die HTTP-Exceptions beschränken;
  • Zeile 9: Die Methode [catch] erhält die Exception und ein Objekt [host], das Zugriff auf die Anfrage und die Antwort bietet;
  • Zeile 11: Eine [HttpException] enthält ihren Statuscode. Jede andere Exception (ein Programmierfehler, eine nicht erreichbare Datenbank) führt zu einem 500-Fehler;
  • Zeile 15: Statt des standardmäßigen JSON zeigt der Filter eine HTML-Seite mit dem richtigen Statuscode an.

Die Datei [src/main.ts]:

import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import { dirname, join } from 'path';
import { AppModule } from './app.module';
import { TimingInterceptor } from './timing.interceptor';
import { ErrorPageFilter } from './error-page.filter';

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule, { logger: ['error', 'warn'] });
  app.useStaticAssets(join(dirname(require.resolve('bootstrap/package.json')), 'dist'), { prefix: '/bootstrap/' });
  app.setBaseViewsDir(join(__dirname, '..', 'views'));
  app.setViewEngine('hbs');
  // ein GLOBALER Interceptor und Filter: sie gelten für alle Routen
  app.useGlobalInterceptors(new TimingInterceptor());
  app.useGlobalFilters(new ErrorPageFilter());
  await app.listen(3000);
  console.log('Server started on http://localhost:3000');
}

bootstrap();
  • Zeile 9: Wir filtern die Meldungen von [NestJS] auf Fehler und Warnungen, damit wir unsere eigenen besser erkennen können;
  • Zeilen 14–15: Der Interceptor und der Filter sind global; sie gelten für alle Actions.

Die Datei [src/calc.controller.ts]:

import { Controller, Get, Param, Render, UseGuards } from '@nestjs/common';
import { BlockGuard } from './block.guard';
import { IntegerPipe } from './integer.pipe';

@Controller('square')
@UseGuards(BlockGuard) // der Guard gilt für alle Actions des Controllers
export class CalcController {
  @Get(':n')
  @Render('square')
  square(@Param('n', IntegerPipe) n: number): object {
    console.log(`5. action square(${n})`);
    if (n === 13) {
      throw new Error('13 brings bad luck'); // ein "unerwarteter" Fehler
    }
    return { n, square: n * n };
  }
}
  • Zeile 6: [@UseGuards] wendet einen Guard auf alle Actions des Controllers an (er kann auch auf eine einzelne Action angewandt werden);
  • Zeile 10: Die Pipe konvertiert den Parameter;
  • Zeilen 12–14: ein „unerwarteter“ Fehler, um den Filter in Aktion zu sehen.

Vier Anfragen: eine normale Berechnung, ein ungültiger Parameter, eine vom Guard blockierte Anfrage und der unerwartete Fehler. Die Serverkonsole:

--- GET /square/7
1. middleware
2. guard (targeted action: square)
3. interceptor (before)
4. pipe (received value: "7")
5. action square(7)
6. interceptor (after, 2 ms)

--- GET /square/abc
1. middleware
2. guard (targeted action: square)
3. interceptor (before)
4. pipe (received value: "abc")
x. exception filter (400: "abc" is not an integer)

--- GET /square/7?block=1
1. middleware
2. guard (targeted action: square)
x. exception filter (403: Forbidden resource)

--- GET /square/13
1. middleware
2. guard (targeted action: square)
3. interceptor (before)
4. pipe (received value: "13")
5. action square(13)
x. exception filter (500: Internal error)

Dieses Protokoll zeigt:

  • die Reihenfolge der Schritte: Middleware, Guard, Interceptor (vorher), Pipe, Action, Interceptor (nachher);
  • eine Exception unterbricht die Kette, wo auch immer sie auftritt, und der Filter erzeugt die Antwort: Der Guard verweigert den Zugriff (403), die Pipe lehnt die Anfrage ab (400), die Action schlägt fehl (500).

Die resultierenden Seiten:

Image

Image

Image

Image

Der Exception-Filter der Fallstudie ([web/html-exception.filter.ts]) folgt diesem Muster, mit einer Ausnahme: Ein 401-Fehler (Benutzer nicht angemeldet) zeigt keine Fehlerseite an, sondern leitet auf die Anmeldeseite um.