Сериализация контролирует способ преобразования объектов в JSON, отправляемый в ответах — что крайне важно, исключая конфиденциальные поля (такие как пароли) и формируя выходные данные. NestJS обрабатывает это с помощью ClassSerializerInterceptor и декораторов class-transformer.
()
() {
..(id);
}
Возврат сущностей базы данных напрямую может раскрыть поля, которые никогда не должны достигать клиента (хэши паролей, внутренние флаги, токены) — серьёзная проблема безопасности и приватности.
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)))
ClassSerializerInterceptor применяет декораторы class-transformer при сериализации ответов, поэтому поля с @Exclude() автоматически удаляются — но только если вы возвращаете экземпляры класса (а не простые объекты).
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!
Частая ошибка: декораторы сериализации работают только на реальных экземплярах класса, поэтому вы должны возвращать экземпляр (ORM-сущности обычно являются экземплярами; вручную созданные простые объекты требуют преобразования).
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.
Контроль сериализации ответов важен как для безопасности, так и для чистого дизайна API.
Наиболее критическая причина — предотвращение утечек конфиденциальных данных — возврат сущностей базы данных напрямую может раскрыть хэши паролей, внутренние поля, токены или другие данные, которые никогда не должны доходить до клиентов, это частая и серьёзная уязвимость.
ClassSerializerInterceptor NestJS с декораторами class-transformer (@Exclude, @Expose, @Transform) предоставляет чистый, декларативный способ формирования ответов — автоматически удаляя исключённые поля, переименовывая и преобразовывая значения.
Понимание этого — необходимые повседневные знания для любого API, который возвращает данные пользователей или доменные данные, а знание ключевой ошибки — что сериализация работает только на экземплярах класса, а не на простых объектах (частый источник багов "почему пароль всё ещё видно?") — практически важно.
Равно ценно и распознавание альтернативного паттерна выделенных DTO ответов (отображение сущностей на явные выходные классы, содержащие только безопасные для клиента поля), что отделяет контракт API от модели базы данных и является самым безопасным подходом для конфиденциальных данных.
Правильный контроль сериализации — отличительная черта безопасных, хорошо спроектированных API NestJS и часто релевантная забота в реальных приложениях, обрабатывающих любые неоткрытые данные.