JSON إلى TypeScript: الأنواع المطابقة للواقع

لماذا تنجرف الأنواع المكتوبة بخط اليد؟

تميل الواجهات المكتوبة من الوثائق أو من الذاكرة إلى التفاؤل. إنهم يضعون علامة على كل شيء موجود، ويفترضون وجود حقل لاغٍ دائمًا، ويفتقدون بهدوء الكائن المتداخل الذي يظهر فقط في الحسابات المميزة. TypeScript ثم يفرض شكلًا لم يعد به الخادم مطلقًا، وتظهر الأسطح `undefined` الأولى في الإنتاج وليس في وقت الترجمة. يؤدي التوليد من استجابات حقيقية إلى عكس العملية: يقوم المترجم بالتحقق من الشكل المرصود بدلاً من الشكل المأمول.

قراءة الملف الذي تم إنشاؤه

يقوم التحويل المفيد بتسمية الكائنات المتداخلة بعد مفاتيحها، ويحافظ على أنواع عناصر المصفوفة سليمة، ويعبر عن عدم اليقين بشكل صريح. انتبه إلى العلامات الثلاثة التي تحمل كل المعنى:

                export interface Order {
  id: string;
  total: number;
  coupon?: string;            // absent in some responses
  shippedAt: string | null;   // present but null until shipped
  items: Array<OrderItem>;
}
              

الفرق بين`coupon?: string`و`shippedAt: string | null`ليست تجميلية. اختياري يعني أن المفتاح قد يكون مفقودًا؛ null يعني أن المفتاح موجود بلا قيمة. تقوم واجهات برمجة التطبيقات بالأمرين معًا، غالبًا في نفس الحمولة، ويؤدي دمجهما إلى دفع التحقق من القيمة الفارغة إلى التعليمات البرمجية التي تفترض سلسلة.

استخدام أكثر من عينة

استجابة واحدة تمثل كل ما هو مطلوب. الصق استجابتين أو ثلاثة - من الناحية المثالية واحدة من حساب فارغ وواحدة من حساب كامل - وسوف تكشف المفاتيح الاختيارية عن نفسها: يصبح الحقل المفقود من أي عينة هو `?`، والحقل الذي يكون في بعض الأحيان خاليًا يصبح اتحادًا مع `null`. هذه هي أرخص ترقية متاحة للصحة، وهذا هو السبب وراء ضرورة إعادة إنشاء الأنواع التي تم إنشاؤها عندما يتغير API بدلاً من كتابتها مرة واحدة.

لا تدع أبدًا الواجهة التي تم إنشاؤها هي الوصف الوحيد لواجهة برمجة التطبيقات (API) الخاصة بك. احتفظ بمخطط أو اختبار عقد بجانبه، بحيث يفشل تغيير الخادم في الإنشاء بدلاً من جلسة المستخدم.

حيث تنتمي الأنواع

• مجلد `types/` أو `api/` مخصص، غير متناثر عبر المكونات.
• ملف واحد لكل نقطة نهاية أو لكل مورد، مع تعليق يذكر نقطة النهاية وتاريخ التقاطها.
• ملاحظة التجديد: المكالمة التي أنتجت الحمولة، حتى يتمكن الشخص التالي من تكرارها.
• عملية تصدير تستهلكها كل من طبقة الجلب والمكونات، لذا فإن التغيير يكسر مكانًا واحدًا بالضبط.

قم بتشغيل الوضع الصارم

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

أنشئ من الحمولات النافعة التي لن تقوم بتحميلها

استجابات واجهة برمجة التطبيقات (API) هي أكثر ملفات JSON حساسية التي يتعامل معها معظم المطورين - بيانات الحساب، والأوامر، والرموز المميزة. إن تشغيل تحويل JSON إلى TypeScript في المتصفح يعني أن الحمولة يتم تحليلها محليًا ولن يتم نقلها مطلقًا، لذا يمكنك لصق استجابة حقيقية دون تنقيحها أولاً، وتستمر الأداة في العمل دون اتصال بالإنترنت.