O que são controllers em NestJS?

Question

Accepted Answer

**Controllers** lidam com **requisições HTTP** recebidas e retornam respostas. Eles definem as rotas de sua aplicação e atuam como ponto de entrada — recebendo requisições, extraindo dados, delegando para services e retornando resultados. Eles mantêm preocupações de roteamento separadas da lógica de negócios.

## Definindo um controller

```ts
import { Controller, Get, Post, Body, Param } from "@nestjs/common";

@Controller("users")          // the route PREFIX → all routes start with /users
export class UsersController {
  constructor(private usersService: UsersService) {}   // inject a service via DI

@Get()                       // GET /users
  findAll() {
    return this.usersService.findAll();
  }

@Get(":id")                  // GET /users/:id
  findOne(@Param("id") id: string) {        // extract the route param
    return this.usersService.findOne(id);
  }

@Post()                      // POST /users
  create(@Body() dto: CreateUserDto) {       // extract the request body
    return this.usersService.create(dto);
  }
}
```

## Como funciona: decoradores mapeiam métodos para rotas

```text
@Controller("users") → route prefix /users
@Get() / @Post() / @Put() / @Patch() / @Delete() → HTTP method + sub-path
Combined: @Get(":id") inside @Controller("users") → GET /users/:id
```

Decorador associam métodos de classe declarativamente a rotas HTTP — limpo e legível, sem registro manual de rotas.

## Decoradores de parâmetro extraem dados da requisição

```ts
@Get(":id")
example(
  @Param("id") id: string,        // route parameter (/users/:id)
  @Query("sort") sort: string,    // query string (?sort=name)
  @Body() body: CreateUserDto,    // request body
  @Headers("authorization") auth: string,  // a header
  @Req() req: Request,            // the raw request object (rarely needed)
) {}
```

Os decoradores de parâmetro do Nest (`@Param`, `@Query`, `@Body`, `@Headers`) extraem de forma limpa exatamente os dados que você precisa — sem análise manual de `req`.

## Controllers devem ser FINOS

```ts
// ✅ controller delegates to a service — stays thin
@Post()
create(@Body() dto: CreateUserDto) {
  return this.usersService.create(dto);   // business logic lives in the SERVICE
}
// ❌ don't put database queries / business logic directly in the controller
```

Melhor prática: mantenha controllers **finos** — eles tratam preocupações HTTP (roteamento, extração de dados, retorno de respostas) e delegam toda lógica de negócios para **services**. Essa separação mantém o código testável e organizado.

## Por que isso importa

Controllers são um bloco de construção fundamental do NestJS — o ponto de entrada para todas as requisições HTTP e onde as rotas de sua API são definidas.

Compreender como decoradores (`@Controller`, `@Get`/`@Post`, `@Param`/`@Body`/`@Query`) mapeiam métodos para rotas e extraem dados da requisição declarativamente é conhecimento essencial do NestJS do dia a dia — é assim que você constrói qualquer endpoint.

Igualmente importante é o princípio de manter controllers **finos** (tratando apenas preocupações HTTP e delegando lógica de negócios para services injetados), que corporifica a filosofia de separação de responsabilidades do NestJS e mantém o código mantível e testável.

Controllers, junto com services e modules, formam a estrutura central de toda aplicação NestJS, tornando-os essenciais para entender desde o início.