Apakah itu DTOs dalam NestJS?

Question

Accepted Answer

**DTO (Data Transfer Object)** ialah satu kelas yang mentakrifkan **bentuk data** yang dihantar ke atau daripada API anda — lazimnya struktur sesuatu request body. DTOs memberikan keselamatan jenis (type safety), bertindak sebagai kontrak yang jelas bagi endpoints, dan (dengan dekorator validation) membolehkan validation input secara automatik.

## Mentakrifkan satu 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;
}
```

Satu DTO ialah kelas biasa yang menerangkan data yang dijangka, dengan **dekorator validation** (daripada `class-validator`) yang menentukan peraturan yang mesti dipenuhi oleh setiap medan.

## Menggunakan satu DTO dalam 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);
}
```

`@Body() dto: CreateUserDto` memberi jenis kepada request body dan — dengan validation pipe diaktifkan — mengesahkannya secara automatik sebelum handler anda berjalan.

## Mengaktifkan validation automatik

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

Dengan `ValidationPipe`, NestJS mengesahkan body masuk berdasarkan dekorator DTO secara automatik — memulangkan ralat 400 berserta butiran jika validation gagal, sebelum kod anda berjalan.

## DTOs lwn Entities

```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 sengaja berbeza daripada database entities — ia mewakili apa yang diterima/dipulangkan oleh API, dipisahkan daripada storan dalaman.

## Variasi dan penggunaan semula

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

## Mengapa ia penting

DTOs ialah satu corak NestJS yang penting yang membawa keselamatan jenis, kontrak API yang jelas, dan validation automatik kepada endpoints anda.

Ia mentakrifkan dengan tepat data apa yang diterima oleh sesuatu endpoint (bentuk request), memberi anda penjenisan pada masa kompilasi dan bertindak sebagai kontrak yang mendokumentasikan dirinya sendiri.

Yang terpenting, digabungkan dengan dekorator `class-validator` dan `ValidationPipe`, ia membolehkan **validation input secara automatik** — request yang cacat atau berniat jahat ditolak dengan ralat yang jelas *sebelum* mencapai logik perniagaan anda, yang amat penting untuk keselamatan dan keteguhan (opsyen `whitelist` juga membuang sifat-sifat yang tidak dijangka).

Memahami DTOs, cara menambah peraturan validation, cara mengaktifkan validation pipe, dan prinsip penting iaitu **memisahkan DTOs daripada database entities** (memisahkan kontrak API daripada storan dalaman) adalah asas untuk membina API NestJS yang selamat, tersusun baik, dan boleh diselenggara.

DTOs muncul dalam hampir setiap endpoint yang menerima input, menjadikannya pengetahuan sehari-hari yang penting.