Serialization يتحكم في كيفية تحويل الكائنات إلى JSON المرسل في الاستجابات — والأهم من ذلك، استبعاد الحقول الحساسة (مثل كلمات المرور) وتشكيل الناتج. يتعامل NestJS مع هذا باستخدام ClassSerializerInterceptor و decorators من class-transformer.
()
() {
..(id);
}
إرجاع كيانات قاعدة البيانات مباشرة قد يكشف حقولاً يجب ألا تصل إلى العميل (hash كلمات المرور، العلامات الداخلية، الرموز) — مشكلة أمان/خصوصية خطيرة.
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 يطبق decorators من class-transformer عند serializing الاستجابات، لذا الحقول مع @Exclude() يتم إزالتها تلقائياً — لكن فقط إذا أرجعت نسخ class instances (وليس plain objects).
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!
خطأ شائع: decorators serialization تعمل فقط على class instances الفعلية، لذا يجب أن تُرجع instance (كيانات ORM عادة تكون instances؛ الكائنات البسيطة المبنية يدويًا تحتاج تحويل).
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.
التحكم في response serialization مهم لكل من الأمان وتصميم API نظيف.
السبب الأكثر أهمية هو منع تسريب البيانات الحساسة — إرجاع كيانات قاعدة البيانات مباشرة قد يكشف hash كلمات المرور، الحقول الداخلية، الرموز، أو بيانات أخرى يجب ألا تصل إلى العملاء، وهي ثغرة شائعة وخطيرة.
ClassSerializerInterceptor في NestJS مع decorators من class-transformer (@Exclude, @Expose, @Transform) توفر طريقة نظيفة وإعلانية لتشكيل الاستجابات — تزيل الحقول المستبعدة تلقائياً، وتعيد التسمية، وتحول القيم.
فهم هذا معرفة أساسية ضرورية لأي API يرجع بيانات مستخدم أو domain، ومعرفة المشكلة الرئيسية — أن serialization تعمل فقط على class instances وليس على plain objects (مصدر متكرر لأخطاء "لماذا تزال كلمة المرور مرئية؟") — مهم عملياً.
بنفس القيمة الاعتراف بنمط بديل من dedicated response DTOs (mapping الكيانات إلى explicit output classes تحتوي على حقول آمنة للعميل فقط)، الذي يفصل عقد API عن نموذج قاعدة البيانات ويكون الأسلوب الأكثر أماناً للبيانات الحساسة.
التحكم الصحيح في serialization علامة فارقة من NestJS APIs آمنة وذات تصميم جيد وقلق متكرر عملياً في التطبيقات التي تتعامل مع أي بيانات غير عامة.