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:

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:




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.