كيفية توليد واجهات TypeScript من JSON

لماذا نولد واجهات TypeScript من JSON

غالباً يبدأ العمل مع API من عينة JSON. قد تأتي العينة من backend، webhook، endpoint تجريبي، صفحة توثيق، أو ملف تصدير. قبل استخدام هذه البيانات في مشروع TypeScript، تحتاج إلى شكل واضح: أسماء الحقول، الكائنات المتداخلة، المصفوفات، النصوص، الأرقام، القيم المنطقية، والقيم غير المعروفة.

كتابة الواجهات يدوياً مناسبة لكائن صغير. لكنها تصبح أبطأ عندما يحتوي JSON على كائنات متداخلة أو مصفوفات أو حقول كثيرة. أداة التوليد تعطيك مسودة أولى سريعة يمكنك مراجعتها وتعديلها.

استخدم JSON إلى كود عندما تريد لصق عينة JSON وتوليد واجهة TypeScript مباشرة داخل المتصفح.

ابدأ بـ JSON صحيح

جودة الواجهة المولدة تعتمد على جودة العينة. إذا كان JSON مضغوطاً في سطر واحد، أو مكسوراً، أو منسوخاً بدون أقواس كاملة، أصلحه أولاً.

افتح منسق JSON، والصق العينة، وتأكد أنها صالحة. JSON المنسق أسهل في الفحص قبل التوليد. سترى الكائنات المتداخلة، والمصفوفات، وقيم null، والحقول التي قد لا تحتاجها في نموذج التطبيق.

هذه الخطوة مهمة خصوصاً عندما تأتي العينة من logs، أو أدوات المتصفح، أو توثيق منسوخ، أو مخرجات ذكاء اصطناعي.

اختر اسم الجذر بوضوح

في JSON إلى كود، اضبط اسم الفئة قبل التوليد. في TypeScript يصبح هذا الاسم هو اسم الواجهة الأساسية.

الأسماء الجيدة تصف الكائن نفسه، وليس فقط اسم الرابط:

• UserProfile
• InvoiceSummary
• ProductSearchResult
• WebhookEvent
• CourseLesson

تجنب أسماء عامة مثل Data أو Response أو Result إلا إذا كان الملف يوضح معناها. أسماء النماذج الواضحة تجعل الكود أسهل في القراءة عند نقله إلى مشروع حقيقي.

ولّد واجهة TypeScript

الصق عينة JSON، واختر تبويب TypeScript، ثم ولّد الكود. تقرأ الأداة بنية الكائن وتنشئ interfaces للكائن الأساسي والكائنات المتداخلة.

مثلاً: النصوص تصبح string، والأرقام الصحيحة والعشرية تصبح number، والقيم المنطقية تصبح boolean، والكائنات تصبح واجهات منفصلة، والمصفوفات تصبح typed arrays حسب أول عنصر.

هذا يعطيك نقطة بداية جيدة، لكنه لا يغني عن المراجعة؛ لأن بيانات API الحقيقية قد تكون أكثر تعقيداً من عينة واحدة.

راجع الأنواع قبل استخدام الكود

بعد التوليد، اقرأ الواجهة كما تراجع كوداً كتبه مطور آخر.

افحص هذه النقاط:

• هل يصل id كرقم أم كنص؟
• هل يمكن أن يغيب حقل في بعض الردود؟
• هل يمكن أن يكون الحقل null رغم أن العينة تحتوي قيمة؟
• هل كل عناصر المصفوفة لها نفس الشكل؟
• هل تحولت أسماء snake_case إلى camelCase؟
• هل أسماء الواجهات المتداخلة واضحة؟

إذا كان API يرسل created_at لكن الواجهة المولدة تستخدم createdAt، قرر هل مشروعك يحول أسماء الحقول أم يحتفظ بأسماء API كما هي. الكود المولد مسودة، ومعايير مشروعك ما زالت مهمة.

انتبه للمصفوفات

كثير من أدوات التوليد تستنتج نوع المصفوفة من أول عنصر. هذا مفيد، لكنه قد يخفي حالات طرفية. إذا كان أول عنصر كاملاً بينما العناصر التالية ناقصة حقولاً، فقد تبدو الواجهة أكثر صرامة من الواقع.

قبل نسخ الكود إلى مشروعك، جرّب التوليد بعينة واقعية. أضف كائناً يحتوي حقولاً قد تكون اختيارية، وكائنات متداخلة، ومصفوفات تشبه الردود الفعلية.

إذا كان لدى backend توثيق رسمي أو OpenAPI schema، فاعتبره المصدر الأقوى. عينة JSON اختصار مفيد، لكنها ليست عقداً نهائياً.

قارن التعديلات بعد المراجعة

قد تولد واجهة، ثم تعدل أسماء الحقول أو تغير أنواع unknown أو تفصل الواجهات المتداخلة في ملفات مستقلة. عند تعديل النموذج، استخدم أداة مقارنة النصوص لمقارنة النسخة المولدة بالنسخة المعدلة.

هذا يساعدك على رؤية التغييرات بدقة قبل لصق الكود في المستودع أو مشاركته مع زميل.

وإذا أردت أن يراجع الذكاء الاصطناعي نموذجاً كبيراً، افحص حجم البرومبت أولاً باستخدام عداد توكنات الذكاء الاصطناعي. عينات JSON والواجهات الطويلة قد تصبح أكبر مما تتوقع.

ملاحظة خصوصية

أداة JSON إلى كود تعمل داخل المتصفح. لا يتم رفع JSON إلى الخادم أثناء التوليد. هذا مفيد لعينات API، وبيانات الاختبار الداخلية، والعمل السريع في الواجهة الأمامية.

مع ذلك احذف الأسرار قبل استخدام أي عينة في عرض، أو توثيق، أو تقرير خطأ، أو برومبت ذكاء اصطناعي. استبدل مفاتيح API، والبريد الإلكتروني، والتوكنات، وأسماء العملاء، والمعرّفات الخاصة بقيم آمنة.

قائمة مراجعة أخيرة

قبل استخدام واجهة TypeScript مولدة:

• تحقق من JSON ونسقه أولاً.
• اختر اسم واجهة أساسية واضحاً.
• ولّد من عينة واقعية.
• راجع النصوص والأرقام والقيم المنطقية والمصفوفات وnull.
• قرر هل ستحتفظ بـ snake_case أم تستخدم camelCase.
• قارن نسختك المعدلة قبل اعتمادها.

للحصول على مسودة سريعة، افتح JSON إلى كود، الصق عينة JSON منظمة، اختر TypeScript، ثم راجع الواجهات المولدة قبل استخدامها في التطبيق.