Serializacja kontroluje, jak obiekty są transformowane do JSON wysyłanego w odpowiedziach — co ważne, wyklucza pola wrażliwe (takie jak hasła) i kształtuje dane wyjściowe. NestJS obsługuje to za pomocą ClassSerializerInterceptor i dekoratora class-transformer.
()
() {
..(id);
}
Zwracanie jednostek bazy danych bezpośrednio może ujawnić pola, które nigdy nie powinny dotrzeć do klienta (hasze haseł, flagi wewnętrzne, tokeny) — poważny problem bezpieczeństwa/prywatności.
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 stosuje dekoratory class-transformer podczas serializacji odpowiedzi, więc pola oznaczone @Exclude() są automatycznie usuwane — ale tylko jeśli zwracasz instancje klasy (nie zwykłe obiekty).
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!
Częsta pułapka: dekoratory serializacji działają tylko na rzeczywistych instancjach klasy, więc musisz zwrócić instancję (jednostki ORM zwykle są instancjami; ręcznie budowane zwykłe obiekty wymagają konwersji).
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.
Kontrolowanie serializacji odpowiedzi jest ważne zarówno dla bezpieczeństwa jak i czystego projektowania API.
Najistotniejszy powód to zapobieganie wyciekom wrażliwych danych — zwracanie jednostek bazy danych bezpośrednio może ujawnić hasze haseł, pola wewnętrzne, tokeny lub inne dane, które nigdy nie powinny dotrzeć do klientów — to powszechna i poważna luka bezpieczeństwa.
ClassSerializerInterceptor NestJS razem z dekoratorami class-transformer (@Exclude, @Expose, @Transform) zapewnia czysty, deklaratywny sposób kształtowania odpowiedzi — automatycznie usuwając pola wykluczone, zmienić nazwy i transformując wartości.
Zrozumienie tego jest podstawową wiedzą codzienną dla każdego API zwracającego dane użytkownika lub domeny, a znanie kluczowej pułapki — że serializacja działa tylko na instancjach klasy, nie na zwykłych obiektach (częsta przyczyna błędów "dlaczego hasło wciąż się pokazuje?") — ma praktyczne znaczenie.
Również cenna jest umiejętność rozpoznawania alternatywnego wzorca dedykowanych DTO odpowiedzi (mapowanie jednostek na jawne klasy wyjściowe zawierające tylko pola bezpieczne dla klienta), które rozdzielają kontrakt API od modelu bazy danych i są najbezpieczniejszym podejściem dla wrażliwych danych.
Prawidłowa kontrola serializacji to cecha bezpiecznych, dobrze zaprojektowanych API NestJS i częsty problem w rzeczywistych aplikacjach obsługujących jakiekolwiek dane niejawne.