0Pricing
NestJS Enterprise Backend APIs · Aula

Modelagem de respostas com ClassSerializerInterceptor

Oculte campos sensíveis e transforme a saída usando @Exclude, @Expose e grupos de serialização.

Modelagem de respostas com ClassSerializerInterceptor é uma aula grátis de NestJS Enterprise Backend APIs no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de NestJS Enterprise Backend APIs, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de NestJS Enterprise Backend APIs inclui 4 aulas no total.

Partes desta aula ainda não foram traduzidas e aparecem em inglês.

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.

Perguntas Frequentes

A aula “Modelagem de respostas com ClassSerializerInterceptor” é grátis?

Sim — o texto completo de “Modelagem de respostas com ClassSerializerInterceptor” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de NestJS Enterprise Backend APIs, atualize para CoddyKit PRO. O curso de NestJS Enterprise Backend APIs inclui 4 aulas no total.

O que vou aprender em “Modelagem de respostas com ClassSerializerInterceptor”?

Oculte campos sensíveis e transforme a saída usando @Exclude, @Expose e grupos de serialização. Você pratica NestJS Enterprise Backend APIs com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar NestJS Enterprise Backend APIs?

Nenhuma experiência prévia é necessária. NestJS Enterprise Backend APIs no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Modelagem de respostas com ClassSerializerInterceptor”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de NestJS Enterprise Backend APIs?

Sim. Cada aula de NestJS Enterprise Backend APIs inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Validação de DTOs Aninhados e de Matrizes
  2. Validadores Personalizados e Restrições Assíncronas
  3. Modelagem de respostas com ClassSerializerInterceptor
  4. Validação condicional e grupos dinâmicos
← Voltar para NestJS Enterprise Backend APIs