0Pricing
NestJS Enterprise Backend APIs · Ders

ClassSerializerInterceptor ile Yanıt Şekillendirme

@Exclude, @Expose ve serileştirme gruplarını kullanarak hassas alanları gizleyin ve çıktıyı dönüştürün.

ClassSerializerInterceptor ile Yanıt Şekillendirme, CoddyKit'te ücretsiz bir NestJS Enterprise Backend APIs dersidir. Bu, 4 dersinin 3. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, NestJS Enterprise Backend APIs öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. NestJS Enterprise Backend APIs kursu toplamda 4 dersten oluşur.

Bu dersin bazı bölümleri henüz çevrilmemiş olup İngilizce olarak gösterilmektedir.

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.

Sıkça Sorulan Sorular

“ClassSerializerInterceptor ile Yanıt Şekillendirme” dersi ücretsiz mi?

Evet — “ClassSerializerInterceptor ile Yanıt Şekillendirme” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve NestJS Enterprise Backend APIs kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. NestJS Enterprise Backend APIs kursu toplamda 4 dersten oluşur.

“ClassSerializerInterceptor ile Yanıt Şekillendirme” dersinde ne öğreneceğim?

@Exclude, @Expose ve serileştirme gruplarını kullanarak hassas alanları gizleyin ve çıktıyı dönüştürün. NestJS Enterprise Backend APIs ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

NestJS Enterprise Backend APIs öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te NestJS Enterprise Backend APIs, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 3. dersidir.

“ClassSerializerInterceptor ile Yanıt Şekillendirme” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu NestJS Enterprise Backend APIs dersinde kod yazıp çalıştırabilir miyim?

Evet. Her NestJS Enterprise Backend APIs dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

  1. İç İçe ve Dizi DTO Doğrulaması
  2. Özel Doğrulayıcılar ve Asenkron Kısıtlamalar
  3. ClassSerializerInterceptor ile Yanıt Şekillendirme
  4. Koşullu Doğrulama ve Dinamik Gruplar
← NestJS Enterprise Backend APIs Sayfasına Dön