تحويل JSON إلى TypeORM Schema!

أدخل JSON وحوله إلى TypeORM Schema! يدعم TypeORM @Entity, @PrimaryGeneratedColumn, @Column, NestJS.
JSON
النتيجة
 

تحويل JSON إلى TypeORM Schema!

يحوّل بيانات JSON إلى صنف entity في TypeORM: صنف @Entity() بمفتاح أساسي، وكل مفتاح آخر كخاصية @Column() مع نوع TypeScript وقابلية null وdecorator من class-validator.

استخدمه لإنشاء أول entity لـ TypeOrmModule.forFeature([...]) في تطبيق NestJS + TypeORM، أو حين تضيف DataSource من TypeORM إلى مشروع Express وتحتاج إلى entities تطابق بيانات لديك أصلًا.

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

  1. الصق السجل المراد تخزينه ككائن، أو عدة سجلات كمصفوفة. الحقول الغائبة في بعض السجلات تصبح أعمدة قابلة لـ null.
  2. أدخل اسم صنف الـ entity في اسم النموذج (الافتراضي MyModel)؛ وsupport ticket يصبح SupportTicket.
  3. احفظه باسم support-ticket.entity.ts وأضفه إلى مصفوفة entities في DataSource أو إلى TypeOrmModule.forFeature([SupportTicket]) في وحدة NestJS.

مثال

المدخلات (JSON)
[
  { "subject": "Login fails on Safari", "priority": 2, "assignee": "jdoe", "closed": false, "opened_at": "2024-06-03T08:12:00Z" },
  { "subject": "Export CSV is empty", "priority": 1, "closed": true, "opened_at": "2024-06-04T14:40:00Z" }
]
المخرجات (TypeORM)
import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
import { IsNotEmpty, IsOptional } from 'class-validator';

@Entity()
export class SupportTicket {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  @IsNotEmpty()
  subject: string;

  @Column()
  @IsNotEmpty()
  priority: number;

  @Column({ nullable: true })
  @IsOptional()
  assignee: string | null;

  @Column()
  @IsNotEmpty()
  closed: boolean;

  @Column({ name: 'opened_at' })
  @IsNotEmpty()
  openedAt: Date;
}

التذكرة الثانية ليس فيها assignee، لذا يكون ذلك العمود @Column({ nullable: true }) بالنوع string | null. وأصبح opened_at الخاصية openedAt بنوع Date، مع name: 'opened_at' الذي يُبقي اسم العمود الأصلي.

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

  • المفتاح الأساسي من بياناتك: غياب مفتاح id أو وجود id عددي صحيح → @PrimaryGeneratedColumn() id: number؛ وid يتجاوز نطاق 32 بت → @PrimaryGeneratedColumn({ type: 'bigint' }) id: string؛ وid نصي مثل UUID → @PrimaryColumn() id: string.
  • أنواع الأعمدة: الأعداد الصحيحة تستخدم @Column() الافتراضي، والعشرية تحصل على type: 'double precision' كي لا تُقتطع الكسور، وأعمدة bigint وأعمدة date التي هي تاريخ فقط نوعها string (يُرجعها TypeORM كنص)، والتاريخ مع الوقت Date.
  • الكائنات والمصفوفات تصبح أعمدة simple-json بنوع Record<string, unknown> أو مصفوفة ذات نوع مثل string[].
  • الأرقام المقتبسة مثل "007" تبقى أعمدة string.
  • الخصائص بصيغة camelCase؛ ويُضاف @Column({ name: 'opened_at' }) كلما اختلف مفتاح JSON.
  • الحقول التي كانت null أو غائبة تحصل على nullable: true و| null و@IsOptional()؛ والبقية تحصل على @IsNotEmpty().

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

ملء entity بعد `nest g resource` مباشرة

استبدل ملف ticket.entity.ts الفارغ الذي أنشأه nest g resource tickets بهذا الناتج؛ فيطابق الـ entity عندها البيانات الوهمية التي كانت الواجهة الأمامية تستخدمها أصلًا، ويصبح Repository<SupportTicket> جاهزًا للاستخدام.

نقطة انطلاق للترحيلات المولَّدة

بعد إنشاء الـ entity، يقارنه typeorm migration:generate بقاعدة البيانات ويكتب ترحيل CREATE TABLE، بما في ذلك أسماء الأعمدة وقابليتها لـ null.

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

  • يخزّن simple-json بيانات JSON كنص، فلا يمكنك التصفية على القيم داخله. على PostgreSQL بدّل إلى type: 'jsonb'، وعلى MySQL إلى type: 'json'، إن احتجت إلى الاستعلام عنها.
  • double precision نوع فاصلة عائمة؛ للأسعار استخدم @Column('decimal', { precision: 10, scale: 2 })، الذي يُرجعه TypeORM كسلسلة نصية.
  • لا تُستنتج العلاقات. الكائنات المتداخلة التي هي في الحقيقة entities أخرى يجب أن تصبح علاقات @ManyToOne أو @OneToMany.

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

بأي اسم جدول يرتبط الـ entity؟

لا اسم في @Entity()، لذا تحوّل التسمية الافتراضية في TypeORM اسم الصنف إلى snake_case: support_ticket. لجدول موجود، مرّر الاسم، مثل @Entity('tickets').

ماذا لو كان emitDecoratorMetadata معطّلًا؟

يقرأ @Column() الخالي من الخيارات نوعه من بيانات reflection الوصفية، فيفشل TypeORM بخطأ في نوع البيانات. فعّله في tsconfig أو اذكر كل نوع صراحة، مثل @Column('varchar').

ما نوع قاعدة البيانات الذي تحصل عليه خاصية Date؟

datetime على MySQL وtimestamp without time zone على PostgreSQL. إن كانت المناطق الزمنية مهمة على PostgreSQL، فبدّل إلى @Column('timestamptz').