O que é middleware no NestJS e como difere de guards/interceptors?

Question

Accepted Answer

**Middleware** é uma função que executa **antes do manipulador de rota**, com acesso aos objetos request e response — o mesmo conceito de middleware Express. NestJS também possui guards, interceptors, pipes e filters, cada um executando em um ponto específico do ciclo de vida da requisição com um propósito distinto. Saber qual usar é fundamental.

## Middleware — executa primeiro, tem req/res

```ts
@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`${req.method} ${req.url}`);   // logging, modifying req
    next();                                      // MUST call next() to continue
  }
}

// register in a module
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes("*");   // apply to routes
  }
}
```

Middleware executa mais cedo, antes de guards/interceptors/pipes, e funciona com `req`/`res` brutos — bom para logging, modificação de requisição, CORS e preocupações compatíveis com Express.

## A ordem completa do ciclo de vida da requisição

```text
Request →
  1. Middleware     (req/res; runs first, Express-style)
  2. Guards         (return true/false → AUTHORIZE or block the request)
  3. Interceptors   (BEFORE the handler)
  4. Pipes          (validate/transform the handler's arguments)
  5. → Route Handler ←
  6. Interceptors   (AFTER the handler — transform the response)
  7. Exception Filters (if an error was thrown anywhere)
→ Response
```

## Para que cada um serve (escolhendo a ferramenta certa)

```text
Middleware  → general pre-processing with req/res (logging, CORS, raw request work)
Guards      → AUTHORIZATION — decide if a request may proceed (auth, roles)
              (return true = allow, false/throw = block)
Interceptors→ wrap the handler — transform request/response, add logging/caching/timing
              (can run logic BEFORE and AFTER the handler)
Pipes       → VALIDATE/TRANSFORM the handler's input arguments (DTO validation)
Filters     → catch and format EXCEPTIONS into responses
```

As distinções-chave: middleware é pré-processamento genérico estilo Express; **guards** lidam especificamente com autorização (um lugar limpo e dedicado para autenticação, ao contrário de misturar em middleware); **interceptors** envolvem o manipulador para transformar respostas ou adicionar comportamentos transversais; **pipes** validam entrada; **filters** tratam erros.

## Quando usar middleware vs guards vs interceptors

```text
Auth check?           → Guard (dedicated, has execution context, returns boolean)
Logging requests?     → Middleware OR an interceptor (interceptor sees the response too)
Transform responses?  → Interceptor (runs after the handler)
Validate a DTO?       → Pipe
Modify raw req early?  → Middleware
```

## Por que isso importa

Compreender middleware e como diferencia de guards, interceptors, pipes e filters é essencial para estruturar aplicações NestJS corretamente — cada um tem um papel específico e executa em um ponto específico do ciclo de vida da requisição, e usar o certo leva a código limpo e idiomático.

Middleware lida com pré-processamento geral estilo Express com req/res brutos.

As distinções cruciais são que **guards** são o lugar dedicado e apropriado para autorização (autenticação/papéis) — muito mais limpo do que middleware para esse propósito — e **interceptors** envolvem o manipulador para transformar respostas e adicionar preocupações transversais (logging, caching, timing) que middleware não consegue fazer facilmente (já que executa antes do manipulador e não vê naturalmente a resposta).

Conhecer a ordem completa do ciclo de vida (middleware → guards → interceptors → pipes → handler → interceptors → filters) e qual ferramenta se encaixa em cada preocupação (autenticação → guard, transformação de resposta → interceptor, validação → pipe, erros → filter) é uma marca de competência em NestJS e evita o erro comum de usar middleware para tudo.

Este é um tópico frequentemente testado e arquiteturalmente importante no framework.