0Pricing
NestJS Enterprise Backend APIs · Leçon

Mise en forme des réponses avec ClassSerializerInterceptor

Masquez les champs sensibles et transformez les sorties à l’aide de @Exclude, @Expose et des groupes de sérialisation.

Mise en forme des réponses avec ClassSerializerInterceptor est une leçon NestJS Enterprise Backend APIs gratuite sur CoddyKit. Ceci est la leçon 3 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage NestJS Enterprise Backend APIs, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours NestJS Enterprise Backend APIs comprend 4 leçons au total.

Certaines parties de cette leçon n'ont pas encore été traduites et s'affichent en anglais.

The Leaky Response Problem

In an enterprise API, your entity classes often carry fields the client must never see: password, refreshToken, internal flags, audit columns.

If you return the raw object straight from your service, NestJS serializes every property to JSON. A single forgotten field becomes a security incident.

  • Goal: shape what leaves the server without rewriting each controller by hand.
  • Tool: the ClassSerializerInterceptor combined with class-transformer decorators.
class User {
  id: number;
  email: string;
  password: string; // never expose this!
}

const user: User = {
  id: 1,
  email: 'ada@corp.io',
  password: 'hashed$2b$10$secret',
};

// Naive JSON.stringify leaks everything
console.log(JSON.stringify(user));

How ClassSerializerInterceptor Works

ClassSerializerInterceptor intercepts the value your handler returns and runs it through class-transformer's instanceToPlain() (a.k.a. classToPlain).

Two conditions must hold for it to do anything useful:

  • The returned value must be an instance of a class (not a plain object literal).
  • That class must be decorated with class-transformer decorators like @Exclude() or @Expose().

If you return a plain {} object, the interceptor has no metadata to act on and passes it through unchanged.

Enabling the Interceptor Globally

You can bind the interceptor at three scopes: globally, per controller, or per handler. For enterprise APIs, binding it globally in main.ts guarantees consistent serialization everywhere.

It needs the Reflector so it can read decorator metadata, which is why we resolve it from the app container.

import { NestFactory, Reflector } from '@nestjs/core';
import { ClassSerializerInterceptor } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalInterceptors(
    new ClassSerializerInterceptor(app.get(Reflector)),
  );
  await app.listen(3000);
}
bootstrap();

Hiding Fields with @Exclude

The simplest way to hide a sensitive field is to decorate it with @Exclude(). The serializer will omit it from the plain output.

Make sure your service returns a real instance (e.g. new UserEntity(...) or a TypeORM entity), otherwise the decorator metadata is never applied.

  • @Exclude() on a property = drop it from every response.
  • Apply it once on the entity; every endpoint returning that entity is protected.
import { Exclude } from 'class-transformer';

export class UserEntity {
  id: number;
  email: string;

  @Exclude()
  password: string;

  @Exclude()
  refreshToken: string;

  constructor(partial: Partial<UserEntity>) {
    Object.assign(this, partial);
  }
}

Seeing instanceToPlain in Action

You do not need NestJS to understand the mechanics. class-transformer's instanceToPlain() is exactly what the interceptor calls under the hood.

Here the password field disappears from the serialized output because of @Exclude(), while id and email survive.

import 'reflect-metadata';
import { Exclude, instanceToPlain } from 'class-transformer';

class UserEntity {
  id: number;
  email: string;

  @Exclude()
  password: string;

  constructor(partial: Partial<UserEntity>) {
    Object.assign(this, partial);
  }
}

const user = new UserEntity({
  id: 1,
  email: 'ada@corp.io',
  password: 'topsecret',
});

console.log(instanceToPlain(user));
// { id: 1, email: 'ada@corp.io' }

Whitelisting with @Expose

@Exclude() is opt-out. The opposite strategy is opt-in: exclude everything by default and explicitly @Expose() only the safe fields.

Set @Exclude() at the class level, then mark each public property with @Expose(). New columns added later stay hidden unless you deliberately expose them, which is the safer default for sensitive data.

import 'reflect-metadata';
import { Exclude, Expose, instanceToPlain } from 'class-transformer';

@Exclude()
class AccountEntity {
  @Expose() id: number;
  @Expose() email: string;

  password: string;       // hidden by class-level @Exclude
  internalRiskScore: number; // also hidden

  constructor(p: Partial<AccountEntity>) {
    Object.assign(this, p);
  }
}

const acc = new AccountEntity({
  id: 7, email: 'grace@corp.io',
  password: 'x', internalRiskScore: 42,
});
console.log(instanceToPlain(acc));
// { id: 7, email: 'grace@corp.io' }

Renaming and Computing Fields with @Expose

@Expose() does more than whitelist. It can rename a property in the output via { name: 'apiName' }, and it can expose a getter as a computed field.

This lets the API surface differ from the internal model without leaking how your columns are named.

import 'reflect-metadata';
import { Expose, instanceToPlain } from 'class-transformer';

class ProfileEntity {
  @Expose({ name: 'userId' })
  id: number;

  firstName: string;
  lastName: string;

  @Expose()
  get fullName(): string {
    return `${this.firstName} ${this.lastName}`;
  }

  constructor(p: Partial<ProfileEntity>) {
    Object.assign(this, p);
  }
}

const prof = new ProfileEntity({ id: 9, firstName: 'Alan', lastName: 'Turing' });
console.log(instanceToPlain(prof));
// { userId: 9, firstName: 'Alan', lastName: 'Turing', fullName: 'Alan Turing' }

Serialization Groups

Sometimes a field should be visible to an admin but hidden from a normal user. Serialization groups solve this with one entity definition.

Tag properties with @Expose({ groups: ['admin'] }). The field only appears when the serializer runs with that group active.

  • No group active = grouped fields are excluded.
  • Group active = grouped fields are included.
import { Exclude, Expose } from 'class-transformer';

export class UserEntity {
  @Expose() id: number;
  @Expose() email: string;

  @Exclude()
  password: string;

  // visible only when serialized with the 'admin' group
  @Expose({ groups: ['admin'] })
  internalNotes: string;

  constructor(partial: Partial<UserEntity>) {
    Object.assign(this, partial);
  }
}

Activating Groups per Handler

In NestJS you choose which groups are active using the @SerializeOptions() decorator on a controller or a handler. The interceptor passes those options into instanceToPlain().

An admin-only route activates the admin group, so internalNotes is included only there. The same UserEntity serves both audiences.

import { Controller, Get, SerializeOptions } from '@nestjs/common';

@Controller('users')
export class UsersController {
  // default route: 'admin' group NOT active -> internalNotes hidden
  @Get(':id')
  findOne() {
    return this.users.findOne();
  }

  @SerializeOptions({ groups: ['admin'] })
  @Get('admin/:id')
  findOneAsAdmin() {
    return this.users.findOne(); // internalNotes now exposed
  }
}

Reproducing Group Behavior Standalone

Run the group logic yourself to internalize it. Passing { groups: ['admin'] } to instanceToPlain() reveals the grouped field; omitting it keeps the field hidden.

This is precisely the toggle @SerializeOptions() controls inside the framework.

import 'reflect-metadata';
import { Exclude, Expose, instanceToPlain } from 'class-transformer';

class UserEntity {
  @Expose() id: number;
  @Exclude() password: string;
  @Expose({ groups: ['admin'] }) internalNotes: string;

  constructor(p: Partial<UserEntity>) { Object.assign(this, p); }
}

const u = new UserEntity({ id: 1, password: 'x', internalNotes: 'flagged' });

console.log(instanceToPlain(u));
// { id: 1 }
console.log(instanceToPlain(u, { groups: ['admin'] }));
// { id: 1, internalNotes: 'flagged' }

Common Pitfalls

Most serialization bugs trace back to a handful of mistakes:

  • Returning plain objects: the interceptor ignores object literals. Always return class instances.
  • Forgetting Reflect metadata: standalone scripts need import 'reflect-metadata' and emitDecoratorMetadata in tsconfig.
  • Nested objects: a child entity is only serialized if you wrap it with @Type(() => Child) so the transformer knows its class.
  • excludeExtraneousValues: enable it with a pure @Expose() whitelist to drop any property lacking @Expose().
import { Expose, Type } from 'class-transformer';

export class AddressEntity {
  @Expose() city: string;
  @Exclude() geoHash: string;
}

export class CustomerEntity {
  @Expose() id: number;

  @Expose()
  @Type(() => AddressEntity) // required for nested serialization
  address: AddressEntity;
}

Quick Check: Choosing the Right Strategy

A teammate added a new ssn column to UserEntity and shipped it. It leaked in the API response. The entity currently uses per-field @Exclude() only on password. What is the most robust fix to prevent future leaks of newly added sensitive fields?

Recap

You now know how to shape NestJS responses declaratively:

  • ClassSerializerInterceptor runs instanceToPlain() on returned class instances; bind it globally for consistency.
  • @Exclude() drops a field (opt-out); class-level @Exclude() plus @Expose() creates a safer opt-in whitelist.
  • @Expose() can rename fields and expose computed getters.
  • Serialization groups with @SerializeOptions({ groups }) let one entity serve different audiences (e.g. admin vs user).
  • Always return real class instances, and use @Type() for nested objects.

Questions Fréquemment Posées

La leçon « Mise en forme des réponses avec ClassSerializerInterceptor » est-elle gratuite ?

Oui — le texte complet de « Mise en forme des réponses avec ClassSerializerInterceptor » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours NestJS Enterprise Backend APIs, passe à CoddyKit PRO. Le cours NestJS Enterprise Backend APIs comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Mise en forme des réponses avec ClassSerializerInterceptor » ?

Masquez les champs sensibles et transformez les sorties à l’aide de @Exclude, @Expose et des groupes de sérialisation. Tu pratiques NestJS Enterprise Backend APIs avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer NestJS Enterprise Backend APIs ?

Aucune expérience préalable n'est requise. NestJS Enterprise Backend APIs sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 3 sur 4.

Combien de temps prend la leçon « Mise en forme des réponses avec ClassSerializerInterceptor » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon NestJS Enterprise Backend APIs ?

Oui. Chaque leçon NestJS Enterprise Backend APIs inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. Validation des DTO imbriqués et des tableaux
  2. Validateurs personnalisés et contraintes asynchrones
  3. Mise en forme des réponses avec ClassSerializerInterceptor
  4. Validation conditionnelle et groupes dynamiques
← Retour à NestJS Enterprise Backend APIs