تحويل JSON إلى Mongoose (TypeScript) Schema!

أدخل JSON وحوله إلى Mongoose (TypeScript) Schema! يدعم NestJS @nestjs/mongoose @Schema, @Prop, SchemaFactory, MongoDB.
JSON
النتيجة
 

تحويل JSON إلى Mongoose (TypeScript) Schema!

يحوّل JSON إلى صنف مخطط @nestjs/mongoose في NestJS: صنف @Schema() مع @Prop() على كل حقل، ومخطط مبني بـ SchemaFactory.createForClass()، ونوع ProductDocument، وكل ذلك في ملف واحد. ويحمل كل حقل أيضًا @IsNotEmpty() أو @IsOptional() من class-validator.

استخدمه حين تحتاج وحدة NestJS إلى مخطط تسجّله عبر MongooseModule.forFeature()، ولديك أصلًا عيّنة من المستند المراد تخزينه، وكتابة كل decorator يدويًا هي الجزء البطيء.

طريقة الاستخدام

  1. الصق مستندًا نموذجيًا في خانة الإدخال. إذا كانت بعض الحقول تظهر أحيانًا فقط، فالصق عدة مستندات كمصفوفة لتُكتشف الحقول الاختيارية.
  2. أدخل اسم الصنف في اسم النموذج (الافتراضي MyModel). كتابة product تُنتج Product وProductDocument وProductSchema.
  3. احفظ النتيجة باسم product.schema.ts وسجّلها بـ MongooseModule.forFeature([{ name: Product.name, schema: ProductSchema }]).

مثال

المدخلات (JSON)
{
  "sku": "KB-87-RED",
  "title": "Mechanical keyboard",
  "price": 89.5,
  "stock": 42,
  "discontinued": false,
  "restocked_at": "2024-03-18"
}
المخرجات (NestJS @nestjs/mongoose)
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { Document, Schema as MongooseSchema } from 'mongoose';
import { IsNotEmpty, IsOptional } from 'class-validator';

export type ProductDocument = Product & Document;

@Schema()
export class Product {
  _id: MongooseSchema.Types.ObjectId;

  @Prop({ type: MongooseSchema.Types.String, required: true })
  @IsNotEmpty()
  sku: string;

  @Prop({ type: MongooseSchema.Types.String, required: true })
  @IsNotEmpty()
  title: string;

  @Prop({ type: MongooseSchema.Types.Number, required: true })
  @IsNotEmpty()
  price: number;

  @Prop({ type: MongooseSchema.Types.Number, required: true })
  @IsNotEmpty()
  stock: number;

  @Prop({ type: MongooseSchema.Types.Boolean, required: true })
  @IsNotEmpty()
  discontinued: boolean;

  @Prop({ type: MongooseSchema.Types.Date, required: true })
  @IsNotEmpty()
  restocked_at: Date;
}

export const ProductSchema = SchemaFactory.createForClass(Product);

العيّنة مستند واحد مملوء بالكامل، لذا يحصل كل حقل على required: true و@IsNotEmpty(). وrestocked_at سلسلة بصيغة تاريخ، فنوعها Date، وتحتفظ الخاصية باسم المفتاح المخزَّن restocked_at.

الميزات المدعومة

  • أنواع Mongoose صريحة، مثل @Prop({ type: MongooseSchema.Types.String, required: true }). ويُستورد Schema الخاص بـ Mongoose باسم MongooseSchema حتى لا يتعارض مع الـ decorator Schema.
  • أنواع TypeScript: number وboolean وDate لسلاسل التاريخ بصيغة ISO 8601، وstring لكل ما عدا ذلك بما فيه السلاسل المكوّنة من أرقام فقط مثل "0042".
  • تُعرَّف الكائنات المتداخلة بـ MongooseSchema.Types.Mixed ونوعها Record<string, unknown>؛ ومصفوفات النوع البسيط الواحد تصبح مثلًا [MongooseSchema.Types.String] مع string[].
  • أسماء الخصائص هي مفاتيح JSON دون تغيير، ومقتبسة عند الحاجة ('home-url': string)، فيطابق الصنف المستندات الموجودة أصلًا في المجموعة.
  • الحقول التي لها قيمة غير فارغة في كل مستند تحصل على required: true مع @IsNotEmpty()؛ والبقية تحصل على @IsOptional() فقط. ويُتخطى مفتاح _id في الإدخال لأن _id: MongooseSchema.Types.ObjectId مُعلن أصلًا.
  • يُولَّد export type ProductDocument = Product & Document للحقن بالشكل @InjectModel(Product.name) model: Model<ProductDocument>.

حالات الاستخدام

إضافة مجموعة إلى خدمة NestJS

أدخل payload حدث أرسله إليك فريق آخر، أو JSON من أداة كشط (scraper)، لتحصل على صنف المخطط، ثم احقنه بـ @InjectModel واستدعِ create أو find فورًا.

نقل نموذج Mongoose من Express إلى NestJS

صدّر بضعة مستندات حفظها النموذج القديم المبني بـ new Schema({...}) والصقها هنا لتعيد كتابته كصنف مبني على الـ decorators دون إسقاط حقول أثناء نسخها يدويًا.

ملاحظات وقيود

  • يقع @IsNotEmpty() و@IsOptional() على صنف المخطط، لكن ValidationPipe يتحقق من كائنات DTO في الـ controllers. للتحقق من الطلبات، انقل هذه الـ decorators إلى صنف DTO أو أنشئ واحدًا.
  • لا خيارات في @Schema()، لذا يتبع اسم المجموعة قاعدة Mongoose في تصغير اسم النموذج وجمعه: products. اضبط @Schema({ collection: 'product' }) إن احتجت إلى اسم محدد.
  • تخرج الحقول الاختيارية مع ذلك دون ? (مثل memo: string). مع strictNullChecks، تغييرها إلى memo?: string أكثر أمانًا.
  • تُخزَّن المستندات الفرعية كـ Mixed لا كمخططات ذات أنواع. للتحقق داخلها، عرّف صنف @Schema() منفصلًا واستخدم @Prop({ type: SubSchema }).

الأسئلة الشائعة

لماذا & Document بدلًا من وراثة Document؟

يتبع ذلك النمط الافتراضي في وثائق NestJS: يبقى صنف المخطط تعريفًا بسيطًا للحقول، ولا يُستخدم ProductDocument إلا حيث تلزم دوال مستندات Mongoose مثل save(). وفي Mongoose 7+ يمكن استخدام HydratedDocument<Product> بديلًا مباشرًا.

ماذا لو كان مشروعي لا يستخدم class-validator؟

احذف السطر import { IsNotEmpty, IsOptional } from 'class-validator' والـ decoratorين على كل حقل. سلوك المخطط يتحكم فيه required داخل @Prop() وحده.

هل يجب أن أحدد type في @Prop()؟

مع emitDecoratorMetadata يمكن استنتاج الأنواع البسيطة، لكن الاستنتاج يفشل مع المصفوفات والاتحادات مثل Date | null. يذكر الكود المولَّد type صراحة حتى يبقى السلوك نفسه حين تغيّر لاحقًا نوع TypeScript لخاصية ما.