¿Qué son los DTOs en NestJS?

Question

Accepted Answer

Un **DTO (Data Transfer Object)** es una clase que define la **forma de los datos** enviados hacia o desde tu API — típicamente la estructura del cuerpo de una solicitud. Los DTOs proporcionan seguridad de tipos, sirven como un contrato claro para endpoints, y (con decoradores de validación) habilitan validación automática de entrada.

## Definiendo un 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;
}
```

Un DTO es una clase simple que describe los datos esperados, con **decoradores de validación** (de `class-validator`) especificando las reglas que cada campo debe satisfacer.

## Usando un DTO en un controlador

```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);
}
```

El `@Body() dto: CreateUserDto` tipifica el cuerpo de la solicitud y — con el validation pipe habilitado — automáticamente lo valida antes de que se ejecute tu manejador.

## Habilitando validación 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
}));
```

Con el `ValidationPipe`, NestJS valida automáticamente los cuerpos entrantes contra los decoradores del DTO — devolviendo un error 400 con detalles si la validación falla, antes de que se ejecute tu código.

## 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.)
```

Los DTOs deliberadamente difieren de las entidades de base de datos — representan lo que la API acepta/devuelve, desacoplados del almacenamiento interno.

## Variaciones y reutilización

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

## Por qué es importante

Los DTOs son un patrón importante de NestJS que aporta seguridad de tipos, contratos de API claros, y validación automática a tus endpoints.

Definen exactamente qué datos acepta un endpoint (la forma de la solicitud), proporcionándote tipificación en tiempo de compilación y sirviendo como contratos autodocumentados.

Crucialmente, combinados con decoradores `class-validator` y el `ValidationPipe`, habilitan **validación automática de entrada** — solicitudes malformadas o maliciosas son rechazadas con errores claros *antes* de llegar a tu lógica de negocio, lo cual es esencial para la seguridad y robustez (la opción `whitelist` también elimina propiedades inesperadas).

Entender los DTOs, cómo agregar reglas de validación, cómo habilitar el validation pipe, y el importante principio de **mantener los DTOs separados de las entidades de base de datos** (desacoplando el contrato de la API del almacenamiento interno) es fundamental para construir APIs de NestJS seguras, bien estructuradas y mantenibles.

Los DTOs aparecen en virtualmente cada endpoint que acepta entrada, convirtiéndolos en conocimiento cotidiano y esencial.