Come si controlla la serializzazione delle risposte in NestJS?

Question

Accepted Answer

**Serializzazione** controlla come gli oggetti vengono trasformati nel JSON inviato nelle risposte — crucialmente, **escludendo campi sensibili** (come le password) e modellando l'output. NestJS gestisce questo con il `ClassSerializerInterceptor` e i decoratori di `class-transformer`.

## Perché è importante

```ts
// ❌ returning an entity directly leaks the password hash!
@Get(":id")
findOne(@Param("id") id: string) {
  return this.usersService.findOne(id);   // { id, name, email, password: "$2b$..." } 😱
}
```

Restituire direttamente le entità del database può esporre campi che non dovrebbero mai raggiungere il client (hash delle password, flag interni, token) — un problema serio di sicurezza/privacy.

## La soluzione: @Exclude e ClassSerializerInterceptor

```ts
import { Exclude } from "class-transformer";

export class User {
  id: number;
  name: string;
  email: string;

@Exclude()                    // this field is REMOVED from responses
  password: string;
}
```

```ts
// enable the serializer interceptor (globally or per-controller)
@UseInterceptors(ClassSerializerInterceptor)
@Controller("users")
export class UsersController {
  @Get(":id")
  findOne(@Param("id") id): User {
    return this.usersService.findOne(id);   // password is automatically stripped
  }
}
// or globally: app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)))
```

Il `ClassSerializerInterceptor` applica i decoratori di `class-transformer` durante la serializzazione delle risposte, quindi i campi con `@Exclude()` vengono automaticamente rimossi — ma **solo se restituisci istanze di classe** (non oggetti semplici).

## Più decoratori di trasformazione

```ts
export class User {
  @Expose()  id: number;          // explicitly include (with excludeAll strategy)
  @Exclude() password: string;     // remove from output

@Expose({ name: "full_name" })   // rename in the output
  name: string;

@Transform(({ value }) => value.toUpperCase())   // transform the value
  code: string;

@Exclude({ toPlainOnly: true })  // exclude only when serializing OUT (not on input)
  internalField: string;
}
```

## Devi restituire istanze di classe

```ts
// ⚠️ the interceptor only transforms CLASS INSTANCES — plain objects pass through unchanged
return new User(data);                 // ✅ decorators apply
return plainToInstance(User, data);     // ✅ convert a plain object to an instance
return { ...data };                     // ❌ plain object — @Exclude is IGNORED!
```

Una trappola comune: i decoratori di serializzazione funzionano solo su istanze di classe effettive, quindi devi restituire un'istanza (le entità ORM sono solitamente istanze; gli oggetti semplici costruiti manualmente necessitano di conversione).

## Alternativa: DTO di risposta dedicati

```text
Instead of decorating entities, map to a separate Response DTO containing only the
fields meant for the client — explicit, decoupled from the DB model, and very safe.
```

## Perché è importante

Controllare la serializzazione delle risposte è importante sia per la **sicurezza** che per un design pulito delle API.

La ragione più critica è prevenire **perdite di dati sensibili** — restituire direttamente le entità del database può esporre hash delle password, campi interni, token, o altri dati che non devono mai raggiungere i client, una vulnerabilità comune e seria.

Il `ClassSerializerInterceptor` di NestJS con i decoratori di `class-transformer` (`@Exclude`, `@Expose`, `@Transform`) fornisce un modo pulito e dichiarativo per modellare le risposte — rimuovendo automaticamente i campi esclusi, rinominando e trasformando i valori.

Comprendere questo è una conoscenza essenziale di tutti i giorni per qualsiasi API che restituisce dati di utenti o di dominio, e conoscere la gotcha principale — che **la serializzazione funziona solo su istanze di classe, non su oggetti semplici** (una fonte frequente di bug "perché la password è ancora visibile?") — è praticamente importante.

Egualmente prezioso è riconoscere il pattern alternativo di **DTO di risposta dedicati** (mappare entità a classi di output esplicite contenenti solo campi sicuri per il client), che disaccoppia il contratto API dal modello di database ed è l'approccio più sicuro per i dati sensibili.

Controllare correttamente la serializzazione è un segno distintivo di API NestJS sicure e ben progettate ed è una preoccupazione frequentemente rilevante nelle applicazioni reali che gestiscono dati non pubblici.