Skip to content

7. O ciclo de vida de uma requisição

Entre a chegada de uma requisição e a execução da action, o [NestJS] envolve vários tipos de objetos, cada um com um papel específico. Já encontramos alguns deles: middleware ([res.locals], [cookie-parser]) e pipes ([ParseIntPipe], [ValidationPipe]). O estudo de caso usa os cinco:

Image

Objeto
Papel
No estudo de caso
middleware
prepara a requisição; ainda não conhece a action
leitura dos cookies, do idioma e da mensagem flash
guard
autoriza ou nega o acesso à action
Autenticação (JWT), papéis
interceptor
código antes e depois da action
o usuário logado, exposto às views
pipe
converte e valida um parâmetro
[ParseIntPipe]
filtro de exceção
converte uma exceção em uma resposta
Páginas de erro HTML, redirecionamento para /login

7.1. Exemplo 24: as cinco etapas

O Exemplo 24 tem uma action que calcula o quadrado de um número e um objeto de cada tipo. Cada um escreve uma linha no console, para que possamos ver a ordem em que ocorrem.

O arquivo [src/logger.middleware.ts]:

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

// 1. o MIDDLEWARE: o primeiro a ver a requisição. Ele ainda não sabe
//    qual action a tratará
@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(); // passamos o controle ao resto da cadeia
  }
}
  • Linha 7: um middleware [NestJS] é uma classe que implementa [NestMiddleware]. Uma simples função, como nos exemplos anteriores, também funcionaria;
  • Linha 11: o middleware deve chamar [next()] para passar o controle à etapa seguinte (ou enviar ele mesmo uma resposta). Caso contrário, a requisição fica bloqueada.

O arquivo [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 {
  // um middleware de classe é registrado no módulo
  configure(consumer: MiddlewareConsumer): void {
    consumer.apply(LoggerMiddleware).forRoutes('*');
  }
}

Linhas 10–12: um middleware baseado em classe é registrado em um módulo que implementa [NestModule]. [forRoutes('*')] o aplica a todas as rotas.

O arquivo [src/block.guard.ts]:

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

// 2. o GUARD: decide se a requisição pode chegar à action.
//    false -> o NestJS lança uma ForbiddenException (403)
@Injectable()
export class BlockGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const req = context.switchToHttp().getRequest<Request>();
    // o guard conhece a action visada (o que o middleware não conhecia)
    console.log(`2. guard (targeted action: ${context.getHandler().name})`);
    return req.query.block !== '1';
  }
}
  • linha 7: um guard implementa [CanActivate];
  • linha 8: seu método [canActivate] recebe o contexto de execução e retorna [true] (a requisição continua) ou [false] (o [NestJS] lança uma [ForbiddenException], código 403);
  • linha 11: diferentemente do middleware, o guard conhece a action de destino ([getHandler()]) e seu controller ([getClass()]). Isso é o que permite a um guard ler os decoradores aplicados à action (veja [@Roles], no próximo capítulo).

O arquivo [src/timing.interceptor.ts]:

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

// 3. o INTERCEPTOR: um código ANTES da action, e DEPOIS dela
@Injectable()
export class TimingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
    console.log('3. interceptor (before)');
    const start = Date.now();
    // next.handle() executa o que vem a seguir: pipes e depois a action. O resultado
    // da action chega no stream retornado (Observable)
    return next.handle().pipe(tap(() => console.log(`6. interceptor (after, ${Date.now() - start} ms)`)));
  }
}
  • linha 6: um interceptor implementa [NestInterceptor];
  • linha 8: o código colocado antes de [next.handle()] é executado antes da action;
  • linha 12: [next.handle()] executa o restante (os pipes e depois a action) e retorna um fluxo [RxJS] ([Observable]) que produzirá o resultado da action. O operador [tap] executa código depois da action, sem modificar seu resultado (o operador [map] permitiria modificá-lo).

O arquivo [src/integer.pipe.ts]:

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

// 4. o PIPE: converte e valida um parâmetro da 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;
  }
}

Um pipe semelhante ao [ParseIntPipe] (veja o Exemplo 12).

O arquivo [src/error-page.filter.ts]:

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

// x. o FILTRO DE EXCEÇÃO: recebe qualquer exceção não tratada, de onde quer
//    que venha (guard, pipe, action...), e constrói a resposta.
//    @Catch() sem argumento: todas as exceções
@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})`);
    // uma página HTML em vez da resposta JSON padrão do NestJS
    res.status(status).render('error', { status, message });
  }
}
  • Linha 7: [@Catch()] sem argumento: o filtro recebe todas as exceções. [@Catch(HttpException)] o limitaria às exceções HTTP;
  • Linha 9: o método [catch] recebe a exceção e um objeto [host] que dá acesso à requisição e à resposta;
  • Linha 11: uma [HttpException] contém seu código de status. Qualquer outra exceção (um erro de programação, um banco de dados inacessível) resulta em um erro 500;
  • linha 15: em vez do JSON padrão, o filtro exibe uma página HTML com o código de status correto.

O arquivo [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');
  // um interceptor e um filtro GLOBAIS: valem para todas as rotas
  app.useGlobalInterceptors(new TimingInterceptor());
  app.useGlobalFilters(new ErrorPageFilter());
  await app.listen(3000);
  console.log('Server started on http://localhost:3000');
}

bootstrap();
  • linha 9: filtramos as mensagens do [NestJS] para exibir apenas erros e avisos, a fim de ver melhor as nossas;
  • linhas 14–15: o interceptor e o filtro são globais; aplicam-se a todas as actions.

O arquivo [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) // o guard vale para todas as actions do controller
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'); // um erro "inesperado"
    }
    return { n, square: n * n };
  }
}
  • linha 6: [@UseGuards] aplica um guard a todas as actions do controller (também pode ser aplicado a uma única action);
  • linha 10: o pipe converte o parâmetro;
  • linhas 12–14: um erro “inesperado”, para ver o filtro em ação.

Quatro requisições: um cálculo normal, um parâmetro inválido, uma requisição bloqueada pelo guard e o erro inesperado. O console do servidor:

--- 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)

Este log mostra:

  • a ordem das etapas: middleware, guard, interceptor (antes), pipe, action, interceptor (depois);
  • uma exceção interrompe a cadeia, onde quer que ocorra, e o filtro gera a resposta: o guard nega o acesso (403), o pipe nega o acesso (400), a action falha (500).

As páginas resultantes:

Image

Image

Image

Image

O filtro de exceção do estudo de caso ([web/html-exception.filter.ts]) segue esse padrão, com uma exceção: um erro 401 (usuário não logado) não exibe uma página de erro, mas redireciona para a página de login.