Serialização controla como objetos são transformados no JSON enviado em respostas — crucialmente, excluindo campos sensíveis (como senhas) e moldando a saída. NestJS lida com isso usando o ClassSerializerInterceptor e decoradores de class-transformer.
()
() {
..(id);
}
Retornar entidades do banco de dados diretamente pode expor campos que nunca deveriam chegar ao cliente (hashes de senha, flags internas, tokens) — um problema sério de segurança/privacidade.
import { Exclude } from "class-transformer";
export class User {
id: number;
name: string;
email: string;
@Exclude() // this field is REMOVED from responses
password: string;
}
// 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)))
O ClassSerializerInterceptor aplica decoradores de class-transformer ao serializar respostas, então campos com @Exclude() são automaticamente removidos — mas apenas se você retornar instâncias de classe (não objetos simples).
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;
}
// ⚠️ 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!
Uma armadilha comum: decoradores de serialização funcionam apenas em instâncias reais de classe, então você deve retornar uma instância (entidades ORM geralmente são instâncias; objetos simples construídos manualmente precisam de conversão).
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.
Controlar a serialização de respostas é importante tanto para segurança quanto para design limpo de API.
A razão mais crítica é evitar vazamentos de dados sensíveis — retornar entidades do banco de dados diretamente pode expor hashes de senha, campos internos, tokens ou outros dados que nunca devem chegar aos clientes, uma vulnerabilidade comum e séria.
O ClassSerializerInterceptor do NestJS com decoradores de class-transformer (@Exclude, @Expose, @Transform) fornece uma maneira limpa e declarativa de moldar respostas — removendo automaticamente campos excluídos, renomeando e transformando valores.
Compreender isso é conhecimento essencial do dia a dia para qualquer API que retorna dados de usuário ou domínio, e conhecer a armadilha principal — que serialização só funciona em instâncias de classe, não em objetos simples (uma fonte frequente de bugs "por que a senha ainda está aparecendo?") — é praticamente importante.
Igualmente valioso é reconhecer o padrão alternativo de DTOs de resposta dedicados (mapeando entidades para classes de saída explícitas contendo apenas campos seguros para o cliente), que desacopla o contrato da API do modelo de banco de dados e é a abordagem mais segura para dados sensíveis.
Controlar adequadamente a serialização é uma marca registrada de APIs NestJS seguras e bem projetadas e uma preocupação frequentemente relevante em aplicações reais que lidam com qualquer dado não público.