O que são DTOs no NestJS?

Question

Accepted Answer

Um **DTO (Data Transfer Object)** é uma classe que define o **formato dos dados** enviados para ou recebidos da sua API — tipicamente a estrutura de um corpo de requisição. DTOs fornecem segurança de tipo, servem como um contrato claro para endpoints e (com decoradores de validação) habilitam validação automática de entrada.

## Definindo um DTO

```ts
import { IsEmail, IsString, MinLength, IsOptional, IsInt, Min } from "class-validator";

export class CreateUserDto {
  @IsEmail()                    // must be a valid email
  email: string;

@IsString()
  @MinLength(8)                 // password at least 8 chars
  password: string;

@IsOptional()                 // optional field
  @IsInt()
  @Min(0)
  age?: number;
}
```

Um DTO é uma classe simples descrevendo os dados esperados, com **decoradores de validação** (de `class-validator`) especificando as regras que cada campo deve satisfazer.

## Usando um DTO em um controller

```ts
@Post()
create(@Body() dto: CreateUserDto) {     // the body is typed AND validated as CreateUserDto
  // dto is guaranteed to be valid here (with the validation pipe enabled)
  return this.usersService.create(dto);
}
```

O `@Body() dto: CreateUserDto` tipifica o corpo da requisição e — com o validation pipe habilitado — valida automaticamente antes que seu handler execute.

## Habilitando validação automática

```ts
// main.ts — turn on the global validation pipe
app.useGlobalPipes(new ValidationPipe({
  whitelist: true,              // strip properties NOT in the DTO (security)
  forbidNonWhitelisted: true,   // reject requests with extra unknown properties
  transform: true,              // auto-transform payloads to DTO instances + convert types
}));
```

Com o `ValidationPipe`, NestJS valida automaticamente corpos de entrada contra os decoradores do DTO — retornando um erro 400 com detalhes se a validação falhar, antes que seu código execute.

## DTOs vs Entidades

```text
DTO    → the shape of data crossing the API boundary (request/response contract)
Entity → the database model (e.g. a TypeORM entity / Prisma model)
→ Keep them SEPARATE: the API contract shouldn't be coupled to the DB schema.
  (A CreateUserDto has password+email; the User entity has id, timestamps, etc.)
```

DTOs propositalmente diferem de entidades de banco de dados — eles representam o que a API aceita/retorna, desacoplados do armazenamento interno.

## Variações e reutilização

```ts
import { PartialType } from "@nestjs/mapped-types";
// derive an UpdateUserDto where all fields are optional — no duplication
export class UpdateUserDto extends PartialType(CreateUserDto) {}
```

## Por que isso importa

DTOs são um padrão importante do NestJS que traz segurança de tipo, contratos claros de API e validação automática para seus endpoints.

Eles definem exatamente quais dados um endpoint aceita (o formato da requisição), fornecendo a você tipagem em tempo de compilação e servindo como contratos auto-documentados.

Crucialmente, combinados com decoradores `class-validator` e o `ValidationPipe`, eles habilitam **validação automática de entrada** — requisições malformadas ou maliciosas são rejeitadas com erros claros *antes* de alcançar sua lógica de negócio, o que é essencial para segurança e robustez (a opção `whitelist` também remove propriedades inesperadas).

Compreender DTOs, como adicionar regras de validação, como habilitar o validation pipe e o importante princípio de **manter DTOs separados de entidades de banco de dados** (desacoplando o contrato da API do armazenamento interno) é fundamental para construir APIs NestJS seguras, bem-estruturadas e mantíveis.

DTOs aparecem em praticamente todo endpoint que aceita entrada, tornando-os conhecimento cotidiano e essencial.