Qual é a ordem do ciclo de vida da solicitação no NestJS?

Question

Accepted Answer

O **ciclo de vida da solicitação** é a sequência precisa de componentes pelos quais uma solicitação passa no NestJS — middleware, guards, interceptors, pipes, handler, depois interceptors novamente, e exception filters em caso de erros. Conhecer a ordem exata é crucial para entender *quando* cada peça de lógica é executada.

## A ordem completa

```text
Incoming Request
   │
   ▼
1. MIDDLEWARE            (Express-style; raw req/res; runs first)
   │
   ▼
2. GUARDS                (authorization — return true to continue, false/throw to block)
   │
   ▼
3. INTERCEPTORS (pre)    (logic BEFORE the handler — start timing, etc.)
   │
   ▼
4. PIPES                 (validate/transform the handler's arguments — DTO validation)
   │
   ▼
5. ROUTE HANDLER         (your controller method runs)
   │
   ▼
6. INTERCEPTORS (post)   (logic AFTER the handler — transform the response)
   │
   ▼
Response

✗ If an exception is thrown ANYWHERE above →
7. EXCEPTION FILTERS     (catch it and format the error response)
```

## Por que a ordem importa (consequências práticas)

```text
• Guards run BEFORE pipes → authorization is checked before input validation
  (no point validating a body for an unauthorized request)
• Pipes run JUST BEFORE the handler → the handler always gets validated/transformed args
• Interceptors straddle the handler → they can measure its duration and transform output
• Filters catch errors from any stage → centralized, consistent error handling
```

## Dentro de cada categoria, a ordenação de escopo se aplica

```text
For each type (guards, interceptors, pipes), they run in this scope order:
  Global → Controller → Method (route)
So a global guard runs before a controller-level guard, before a route-level guard.
```

## Um exemplo concreto

```ts
@Controller("users")
@UseGuards(AuthGuard)                    // 2. checks authorization
@UseInterceptors(LoggingInterceptor)     // 3 (pre) + 6 (post)
export class UsersController {
  @Post()
  create(@Body() dto: CreateUserDto) {    // 4. ValidationPipe validates dto, 5. handler runs
    return this.usersService.create(dto);
  }
}
// Flow: middleware → AuthGuard → LoggingInterceptor(before) → ValidationPipe →
//       create() → LoggingInterceptor(after) → response (or → filter on error)
```

## Por que isso importa

Entender a ordem do ciclo de vida da solicitação é fundamental para construir aplicações NestJS corretamente — determina exatamente *quando* cada peça de lógica transversal é executada, o que afeta diretamente as decisões de design e o debugging.

A ordenação tem significância real e prática: **guards são executados antes de pipes**, então a autorização é verificada corretamente antes de se incomodar em validar entrada (uma solicitação não autorizada é rejeitada antes da validação); **pipes são executados logo antes do handler**, garantindo que o handler sempre receba argumentos validados e transformados; **interceptors envolvem o handler** (executando antes *e* depois), que é precisamente o que lhes permite cronometrar execução e transformar respostas; e **exception filters capturam erros de qualquer estágio**, permitindo tratamento centralizado de erros.

Conhecer essa ordem — mais a ordenação de escopo dentro da categoria (global → controller → method) — permite colocar a lógica no componente certo, prever o fluxo de execução, debugar por que algo é executado (ou não) quando esperado, e arquitetar recursos corretamente.

Isso une todas as peças de tratamento de solicitação do framework (middleware, guards, interceptors, pipes, filters) em um modelo mental coerente, tornando-o um tópico importante e frequentemente testado que reflete o entendimento genuíno de como NestJS processa solicitações.