JavaScript / متقدم: الجدولة والواجهات الموثوقة / الدرس 18
محولات API وبنية واجهة صريحة
اجمع عقود اللغة في بنية واجهة قابلة للصيانة. افصل النقل والتحليل وقواعد المجال وانتقالات الحالة والعرض وأدلة التسليم بمحولات مصطنعة.
في هذه الصفحة
أهداف الدرس
- التحقق من النقل ونتائج المجال منفصلين.
- تمثيل حالة الواجهة بانتقالات صريحة.
- اختبار المحولات والمسارات عند حدود مهمة.
اختيار مسؤوليات قليلة واضحة
يمكن لعميل صغير فصل محول النقل وفاك البيانات والحسابات والانتقالات وعرض DOM دون إطار كبير. يتولى المحول HTTP والإلغاء ويفحص الفاك البنية وتعمل القواعد على الصالح ويقرر الانتقال الحالة ويعرضها العارض بإتاحة. اجعل الاعتمادات اتجاهية كي لا تحتاج القواعد document أو شبكة. تفيد البنية بوضوح الحدود لا بطبقات تعيد تسمية استدعاء وتخفي مالك الخطأ والهوية والتنظيف.
لا يعني نجاح النقل صلاحية المجال
تفي fetch عادة لاستجابات HTTP الخاطئة مثل 404 و500، فافحص ok أو سياسة الحالة قبل فك النجاح. قد يفشل JSON وقد تصح صياغته وتخطئ بنيته. يحقن المثال دالة شبيهة بالجلب مصطنعة ويتحقق من سجل صغير بلا طلب. يحمل المحول الحقيقي إشارة مملوكة ويمنع تسرب الرموز. قرر أمان الإعادة؛ فضياع استجابة كتابة لا يثبت أنها لم تحدث.
async function loadCourse(fetchLike) {
const response = await fetchLike();
if (!response.ok) throw new Error("course HTTP failure");
const data = await response.json();
if (typeof data.title !== "string" || !Number.isInteger(data.seats) || data.seats < 0) {
throw new TypeError("invalid course shape");
}
return { title: data.title, seats: data.seats };
}
const course = await loadCourse(async () => ({
ok: true, json: async () => ({ title: "DOM", seats: 2 })
}));
console.log(course.title, course.seats);
DOM 2
توفر الاستجابة المحقونة بيانات معلومة، وتبقى حالة HTTP وفك JSON وفحص البنية خطوات منفصلة.
نمذجة حالات بدلاً من أعلام متناقضة
قد تصف أعلام loading وfailed وloaded تركيبات مستحيلة. تمثل حالة موسومة خمولاً أو تحميلاً بهوية أو جاهزية ببيانات صالحة أو خطأ برسالة آمنة. تقبل الانتقالات أحداثاً معرفة وتتجاهل ما لا ينتمي للطلب النشط. اجعل المنطق خالصاً حيث يمكن لفحص قبل وبعد. يتبع العرض حالة متماسكة بدلاً من تفسير متغيرات مبعثرة. ميّز الفراغ من فشل التحميل واحتفظ بالقديم فقط بسياسة منتج صريحة.
تجاهل الحدث القديم عند حد الحالة
يبدأ المثال الطلب اثنين ويتلقى نجاحاً قديماً لواحد ثم يقبل اثنين؛ فيبقى التحميل بعد القديم. يحدد التطبيق أيضاً الفشل والإلغاء والإعادة والتحرير ويفحص البيانات. لا تعدل DOM داخل الدالة لئلا تخلط القرار بالأثر وتصعّب الإعادة. يعلن العارض الحالات بإتاحة وتملك طبقة التنسيق بدء العمل وتحرير المستمعين والإشارات.
function transition(state, event) {
if (event.type === "load") return { status: "loading", request: event.id };
if (event.type === "success" && state.status === "loading" && state.request === event.id) {
return { status: "ready", data: event.data };
}
return state;
}
let state = transition({ status: "idle" }, { type: "load", id: 2 });
state = transition(state, { type: "success", id: 1, data: "old" });
console.log(state.status);
state = transition(state, { type: "success", id: 2, data: "DOM" });
console.log(state.status, state.data);
loading
ready DOM
يتجاهل القديم بلا عرض وينتج الحالي حالة جاهزية غير مبهمة.
التحقق من نتيجة المستخدم المركبة
اختبر القواعد بأمثلة دقيقة والمحولات باستجابات مضبوطة والانتقالات بتسلسلات، ورحلة متصفح بلوحة المفاتيح وملاحظة الحفظ عند الحاجة. احتفظ بفحص عقد حقيقي مصرح ولا تعتبر البديل دليلاً على الخادم. وثّق البيئات والتحميل والأخطاء وملكية الإلغاء والافتراضات غير المختبرة. يبقى الأداء والأمن والإتاحة خصائص للتفاعل الكامل لا شارات إطار. تحدد حجة التسليم ما رُصد وما جُهل وكيف يسهل التصميم التغيير.
الأخطاء الشائعة وإصلاحها
معاملة HTTP 500 كبيانات نجاح
- لماذا يحدث؟
- الخلط بين وفاء fetch وقبول الاستجابة.
- كيف تصلحه؟
- فحص سياسة الحالة قبل فك النجاح.
- كيف تتجنب تكراره؟
- اختبار أخطاء HTTP وJSON والبنية منفصلة.
وصف أعلام متعددة حالات متناقضة
- لماذا يحدث؟
- توزيع الانتقالات بين الاستدعاءات.
- كيف تصلحه؟
- استخدام حالات موسومة وأحداث انتقال مملوكة.
- كيف تتجنب تكراره؟
- اختبار التسلسلات والنتائج القديمة والمرفوضة.
اعتبار المحول البديل دليلاً على الخادم
- لماذا يحدث؟
- الخلط بين المحاكاة وتكامل العقد الحقيقي.
- كيف تصلحه؟
- الاحتفاظ بتكامل مضبوط وبيان الافتراضات غير المختبرة.
- كيف تتجنب تكراره؟
- مراجعة التجهيز عند تغير العقد الخارجي.
اختبر فهمك
1. الاستجابة JSON صالح لكن seats تساوي "two". أين ترفض؟
اعرض الحل المشروح
ارفض في فاك الحد قبل سجل المجال أو الجاهزية. يفحص JSON الصياغة لا أنواع الحقول. أعد أو ارمِ الخطأ الآمن المتفق عليه وأبقِ الواجهة في حالة فشل معرفة وافحص عدم استخدام السجل للتسجيل.
2. أعطِ مجموعة أدلة دنيا لواجهة بحث دورات جديدة.
اعرض الحل المشروح
أدرج أمثلة ترشيح خالصة ورفض HTTP والبنية وانتقالات طلب معكوسة ورحلة لوحة مفاتيح تشمل التحميل والفراغ والتصحيح والنتائج الحالية. وثّق غير المدعوم والافتراضات؛ وهذه بداية مبررة لا إثبات شامل.
أهم ما تعلمته
- افصل النقل والفك وقرارات المجال والحالة والعرض.
- تفيد البنية بوضوح الملكية والأدلة.