0Pricing
NestJS Enterprise Backend APIs · 课时

使用 ClassSerializerInterceptor 定制响应

使用 @Exclude、@Expose 和序列化分组隐藏敏感字段并转换输出。

使用 ClassSerializerInterceptor 定制响应 是 CoddyKit 上的免费 NestJS Enterprise Backend APIs 课时。 这是第 3 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 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 定制响应」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 NestJS Enterprise Backend APIs 课程的其余内容，请升级到 CoddyKit PRO。 NestJS Enterprise Backend APIs 课程共包含 4 节课。

「使用 ClassSerializerInterceptor 定制响应」这节课中我会学到什么？

使用 @Exclude、@Expose 和序列化分组隐藏敏感字段并转换输出。 你通过在浏览器中直接运行的动手代码来练习 NestJS Enterprise Backend APIs，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 NestJS Enterprise Backend APIs 需要有经验吗？

无需任何先前经验。CoddyKit 上的 NestJS Enterprise Backend APIs 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 4 节。

「使用 ClassSerializerInterceptor 定制响应」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 NestJS Enterprise Backend APIs 课中编写并运行代码吗？

能。每节 NestJS Enterprise Backend APIs 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. 嵌套对象与数组 DTO 验证
  2. 自定义验证器与异步约束
  3. 使用 ClassSerializerInterceptor 定制响应
  4. 条件验证与动态分组
← 返回 NestJS Enterprise Backend APIs