0Pricing
NestJS Enterprise Backend APIs · 강의

ClassSerializerInterceptor를 활용한 응답 구성

@Exclude, @Expose 및 직렬화 그룹을 사용해 민감한 필드를 숨기고 출력을 변환합니다.

ClassSerializerInterceptor를 활용한 응답 구성은(는) CoddyKit의 무료 NestJS Enterprise Backend APIs 강의입니다. 이것은 4개 중 3번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 NestJS Enterprise Backend APIs 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. NestJS Enterprise Backend APIs 강의에는 총 4개의 강의가 포함되어 있습니다.

이 강의의 일부는 아직 번역되지 않았으며 영어로 표시됩니다.

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.

자주 묻는 질문

“ClassSerializerInterceptor를 활용한 응답 구성” 강의는 무료인가요?

네 — “ClassSerializerInterceptor를 활용한 응답 구성” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 NestJS Enterprise Backend APIs 강의 전체를 잠금 해제할 수 있습니다. NestJS Enterprise Backend APIs 강의에는 총 4개의 강의가 포함되어 있습니다.

“ClassSerializerInterceptor를 활용한 응답 구성”에서 뭘 배우나요?

@Exclude, @Expose 및 직렬화 그룹을 사용해 민감한 필드를 숨기고 출력을 변환합니다. 브라우저에서 직접 실행하는 실습 코드로 NestJS Enterprise Backend APIs을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

NestJS Enterprise Backend APIs을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 NestJS Enterprise Backend APIs은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 3번째 강의입니다.

“ClassSerializerInterceptor를 활용한 응답 구성” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 NestJS Enterprise Backend APIs 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 NestJS Enterprise Backend APIs 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

  1. 중첩 객체 및 배열 DTO 검증
  2. 사용자 지정 검증기와 비동기 제약 조건
  3. ClassSerializerInterceptor를 활용한 응답 구성
  4. 조건부 검증과 동적 그룹
← NestJS Enterprise Backend APIs(으)로 돌아가기