واجهات برمجة التطبيقات الآمنة نوعياً: التحقق في وقت التشغيل باستخدام TypeScript

وهم وقت الترجمة

يَعِد TypeScript بشيء لا يستطيع تقديمه بالكامل: أنّ الأنواع المكتوبة في وقت الترجمة ستصمد في وقت التشغيل. بالنسبة للشيفرة من جانب العميل البحتة بدون دخل خارجي، الوعد صحيح تقريباً. لحظة عبور البيانات حدّ ثقة — استجابة HTTP، أو رابط مُحلَّل، أو رسالة من مستمع postMessage، أو قيمة مقروءة من التخزين المحلي — تصبح الأنواع تأكيدات لا ضمانات. قد تتوافق قيم وقت التشغيل أو لا تتوافق، والفجوة بين قد وست هي حيث تعيش حوادث الإنتاج.

تعلّمت هذا الدرس بالطريقة المكلفة، حين غيّر فريق خلفيّ شكل استجابة واجهة برمجة تطبيقات، وواجهتنا الأماميّة ب compiled بنظافة، واجتازت كلّ اختبارات الوحدة، وأصدرت ميزة تحطّمت لكلّ مستخدم كان حسابه يفتقر حقل اختياري مفقود. TypeScript وثق بنوع الاستجابة لأنّنا أخبرناه بذلك. لم يكن نظام الأنواع مخطئاً؛ بل كان اندماجنا معه كذلك.

التحقّق في وقت التشغيل كطبقة مفقودة

الحلّ ليس التخلّي عن TypeScript — فوائده في وقت الترجمة حقيقيّة وجوهريّة — بل إضافته بطبقة تحقّق وقت تشغيل عند كلّ حدّ ثقة. النمط أصبح راسخاً الآن: عرّف مخطّطاً يصف الشكل المتوقّع للبيانات الخارجيّة، وتحقّق من البيانات الواردة مقابل المخطّط، واستنتج أنواع TypeScript من المخطّط بحيث لا يستطيع الاثنان الانجراف.

• Zod — تعريف مخطّط TypeScript-أوّل مع استنتاج أنواع ممتاز. المعيار الفعلي للمشاريع الجديدة.
• Valibot — بديل معياري ببصمة حزمة أصغر، مناسب للتطبيقات الحسّاسة للحجم.
• TypeBox — متوافق مع JSON Schema، مثالي عندما يجب أن يخدم المخطّط أيضاً كموصّف عقد واجهة برمجة تطبيقات.
• ArkType — محسّن للأداء والراحة، بتركيب يحاكي TypeScript نفسه عن كثب.

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

الاندماج الناضج يعامل المخطّط كمصدر للحقيقة ويشتقّ كلّ شيء آخر منه. تعرّف الخلفيّة شكل الاستجابة كمخطّط؛ تستورد الواجهة الأماميّة المخطّط وتتحقّق من الاستجابات ضده؛ تُستنتج أنواع TypeScript من المخطّط على الجانبين. هذا يلغي صنفاً كاملاً من أخطاء الانجراف لأنّ هناك نتاجاً واحداً — المخطّط — مقيّداً به الجانبان الخلفيّ والأماميّ.

النوع ادّعاء حول البيانات. المخطّط اختبار لذلك الادّعاء. النظام الذي يعامل الأنواع كادّعاءات والمخطّطات كاختبارات متين؛ النظام الذي يعامل الأنواع كضمانات حادث ينتظر الحدوث.

أين تتحقّق (وأين لا تتحقّق)

ليس كلّ حدّ يحتاج تحقّقاً، والتحقّق غير المميّز ينتج شيفرة آمنة لكنّ بطيئة ومطوّلة. القاعدة التي أستخدمها بسيطة: تحقّق عند حدود الثقة، اثق ضمنها. استجابة HTTP من خلفيّتك الخاصّة حدّ ثقة — حتى خلفيّتك الخاصّة تستطيع نشر تغيير كاسر بينما تكتب العميل ووقت تحميل المستخدم للصفحة. قيمة حسبتها داخل الدالة الحاليّة ليست حدّ ثقة — التحقّق منها تكراريّ.

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

التغيير الثقافي

تبنّي التحقّق في وقت التشغيل تغيير ثقافيّ بقدر ما هو تقنيّ. يتطلّب اتّفاق فرق الخلفيّة والأماميّة على نتاج مخطّط مشترك، ممّا يتطلّب محادثات حول من يملك المخطّط وأين يعيش وكيف يتطوّر. هذه المحادثات غير مريحة لأنّها تظهر حدوداً تنظيميّة يفضّل الجانبان تركها ضمنيّة. وهي أيضاً المحادثات التي تمنع حوادث الانجراف التي وُجد التحقّق في وقت التشغيل لالتقاطها.

الفرق التي تتبنّى هذا النمط بنجاح تعامل المخطّط كعقد حيّ: مُصدَّر ومُراجَع ومُغيَّر عبر عمليّة متعمّدة بدلاً من تحرير عابر. الاستثمار في تلك العمليّة يؤتي ثماره ليس في المسار السعيد — حيث ينجح التحقّق دائماً — بل في المسار التعيس، حيث يُلتقط التغيير الكاسر عند الحدّ ويُعالج برشاقة بدلاً من الانتشار إلى تحطّم يواجهه المستخدم. أمان النوع في وقت التشغيل ليس بارانويا؛ بل مهنيّة.