كل عميل API يبدأ بالطريقة نفسها: fetch(url).then((r) => r.json())، التي تُعيد Promise<any>، فتمتلئ قاعدة الكود ببطء بـ as Order وas Order[] في مواضع الاستدعاء. كل تحويل ادّعاءٌ صغير غير مُراجَع بشأن الخادم. هذا الدرس يجمع القسم كله لبناء عميل لا يكتب فيه المستدعون أي تحويل أو وسيط نوع، ويفشل فيه المسار الخاطئ أو الحقل الناقص أو المعرّف المكتوب بنوع خاطئ في الترجمة.
ابدأ بكتابة كل endpoint مرة واحدة، كـ type:
\ntype OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order = { id: number; status: OrderStatus; totalCents: number };\ntype CancelledOrder = { id: number; status: 'cancelled'; cancelReason: string };\ntype Page<T> = { items: T[]; nextCursor: string | null };\n\ntype Routes = {\n 'GET /orders/:id': { input: { id: number }; output: Order };\n 'GET /orders': { input: { status?: OrderStatus; cursor?: string }; output: Page<Order> };\n 'POST /orders/:id/cancel': { input: { id: number; reason: string }; output: CancelledOrder };\n};كل مفتاح يسمّي endpoint، الطريقة والمسار معًا. وكل قيمة تقول ما يأخذه الـ endpoint وما يُعيده. لن يذكر أي شيء آخر في العميل Order أو Page مباشرة؛ كل ذلك سيُشتقّ من هذا الجدول. وإضافة endpoint تعني إضافة سطر واحد هنا.
الآن التوقيع. تريد أن يكتب المستدعي المسار والمدخل، ويحصل على نوع الاستجابة الصحيح:
\nasync function call<R extends keyof Routes>(\n route: R,\n input: Routes[R]['input'],\n): Promise<Routes[R]['output']> {\n // implementation below\n}\n\nconst order = await call('GET /orders/:id', { id: 1042 }); // Order\nconst page = await call('GET /orders', { status: 'shipped' }); // Page<Order>\nawait call('POST /orders/:id/cancel', { id: 1042 });\n// Error: Argument of type '{ id: number; }' is not assignable to parameter\n// of type '{ id: number; reason: string; }'.\n// Property 'reason' is missing in type '{ id: number; }' but required in type …كل فكرة من هذا القسم تعمل هنا. R يظهر ثلاث مرات، رابطًا المسار بالمدخل والمخرج. قيده، keyof Routes، هو union من قيم نصية حرفية، فيُستنتج الوسيط على أنه القيمة الحرفية 'GET /orders/:id' لا string. ولـ R موقع استنتاج واحد فقط، هو route؛ أما input فـيستخدم R فقط، عبر الوصول بالفهرس Routes[R]['input']. يستنتج TypeScript المسار، ثم يفحص المدخل مقابل ما يحتاجه ذلك المسار. لا حاجة إلى NoInfer، لأنه لا يوجد ما يمكن أن يساهم بمرشّح آخر.
داخل call، نوع input هو Routes[R]['input'] لـ R ما مجهول. لا يستطيع TypeScript معرفة الحقول التي فيه، فبناء الرابط يحتاج إلى تحويل. وهذا مقبول، ما دام يحدث في مكان واحد بالضبط:
type Transport = (method: string, path: string, body: unknown) => Promise<unknown>;\n\nfunction createClient(transport: Transport) {\n return async function call<R extends keyof Routes>(\n route: R,\n input: Routes[R]['input'],\n ): Promise<Routes[R]['output']> {\n const [method, template] = route.split(' ');\n // The route map guarantees every :param has a matching input field.\n const values = input as Record<string, unknown>;\n const rest: Record<string, unknown> = { ...values };\n const path = template.replace(/:(\\w+)/g, (_, name: string) => {\n delete rest[name];\n return encodeURIComponent(String(values[name]));\n });\n const result = await transport(method, path, method === 'GET' ? undefined : rest);\n return result as Routes[R]['output'];\n };\n}هناك تحويلان، كلاهما مشروح بتعليق، وكلاهما في الدالة الوحيدة التي يمرّ بها كل طلب. يحصل المستدعون على API مفحوص بالكامل، والمراجع الذي يريد تدقيق الأجزاء غير الآمنة يقرأ عشرة أسطر. قارن ذلك بقاعدة كود يقول فيها كل موضع من مئتي موضع استدعاء as Order.
حقن الـ transport قرار تصميمي يستحق التقليد. التطبيق الحقيقي يمرّر دالة تستدعي fetch؛ والاختبارات تمرّر نسخة مزيّفة تسجّل الطلبات وتُعيد بيانات جاهزة. والأنواع لا تهتم بأيّهما.
للعملاء الحقيقيين endpoints لا تأخذ شيئًا، مثل 'GET /me'. مع هذا التصميم تعطيها input: {} ويكتب المستدعون call('GET /me', {}). ذلك الكائن الفارغ عيبٌ صغير، وهو مقايضة عادلة حاليًا: البديل توقيع يجعل input اختياريًا لبعض المسارات فقط، وهذا يحتاج إلى conditional type. ستملك تلك الأداة بعد الـ Conditional Types والتوزيع و infer، ولن يمسّ التغيير إلا التوقيع، لا موضع استدعاء واحدًا.
والأمر نفسه مع سلاسل الاستعلام مقابل أجسام الطلبات، أو الترويسات، أو أنواع الأخطاء لكل مسار. كلٌّ منها خاصية إضافية في قيم خريطة المسارات وعملية بحث إضافية في التوقيع. ويبقى شكل الحل كما هو: صِفه مرة واحدة في الجدول، واشتقّه في كل مكان آخر.
\nانظر إلى ما لا يضطر المستدعي إلى فعله أبدًا: كتابة <Order>، أو التحويل، أو استيراد أنواع الاستجابات، أو تذكّر أيّ endpoints تحتاج أيّ حقول. أفضل الـ APIs الـ generic تبدو كأنها بلا أنواع إطلاقًا، لأن كل نوع فيها مستنتج من شيء كان على المستدعي كتابته على أي حال (هنا، اسم المسار).
في التمرين ستبني هذا العميل مقابل transport مزيّف. وبه ينتهي قسم الـ generics. القسم 3 يفكّك عوامل الأنواع (type operators) التي كنت تستعيرها (keyof والوصول بالفهرس) ويضيف الـ mapped والـ conditional والـ template literal types، كي تشتقّ المزيد من مصدر حقيقة واحد.
بالنظر إلى call<R extends keyof Routes>(route: R, input: Routes[R]['input']): Promise<Routes[R]['output']>، كيف يُحدَّد R في call('GET /orders/:id', { id: 1042 })؟
input، بمطابقة شكله مع كل مسار.","why":"نوع input هو Routes[R]['input']، الذي يعتمد على R؛ يُفحص بعد أن يُعرف R، ولا يُستخدم لإيجاده."},{"text":"من نص المسار، الذي يبقى القيمة الحرفية 'GET /orders/:id' لأن القيد union من قيم نصية حرفية.","why":"صحيح. تبقى القيمة الحرفية حرفية بفضل القيد keyof Routes، وتُبحث الأنواع الأخرى انطلاقًا منها."},{"text":"من نوع الإرجاع المعلَن في موضع الاستدعاء.","why":"يمكن لـ TypeScript استخدام نوع إرجاع سياقي في بعض الحالات، لكن هنا وسيط المسار هو من يقرّر كل شيء."}],"answer":1},{"q":"يحتاج تنفيذ call إلى قراءة معاملات المسار من input، ونوعه Routes[R]['input']. ما النهج الأكثر معقولية؟
input: any كي يستطيع التنفيذ قراءة أي شيء.","why":"هذا يرمي الفحص الذي يعتمد عليه المستدعون، وهو الغاية من العميل أصلًا."},{"text":"اكتب overload لكل مسار كي يكون كل تنفيذ محدّدًا.","why":"هذا يكرّر خريطة المسارات ويجب تحديثه يدويًا مع كل endpoint جديد."},{"text":"أبقِ التوقيع العام generic وعامل input كـ Record<string, unknown> في الداخل، مع تحويل واحد مشروح بتعليق.","why":"صحيح. التحويل محلّي، يُراجَع مرة واحدة، وغير مرئي للمستدعين، الذين يحتفظون بالفحص الكامل."}],"answer":2},{"q":"يعلن عميلك أن 'GET /orders/:id' يُعيد Order. يطلق الخادم تغييرًا يعيد تسمية status إلى state. ماذا يفعل TypeScript؟
order.status فيحصل على undefined وقت التشغيل، ويفشل في مكان ما لاحقًا.","why":"صحيح. خريطة المسارات وعدٌ بشأن الخادم لا يستطيع TypeScript فحصه. تحقّق من الاستجابات عند الحدود لتلتقط هذا مبكرًا."},{"text":"يبلّغ عن خطأ على سطر call في المرة القادمة التي تبني فيها المشروع.","why":"لا يرى TypeScript استجابة الخادم أبدًا. إنه يفحص كودك فقط مقابل الأنواع التي أعلنتها."},{"text":"يرمي خطأ نوع وقت التشغيل داخل call.","why":"تُمحى الأنواع؛ لا شيء يفحص الاستجابة وقت التشغيل ما لم تكتب ذلك الفحص بنفسك."}],"answer":0},{"q":"لماذا يُفضَّل تحديد المسار كنص واحد مثل 'POST /orders/:id/cancel' بدل تمرير الطريقة والمسار كوسيطين منفصلين؟
POST بمسار لا يقبل إلا GET."},{"text":"لأن fetch تتطلّب الطريقة داخل الرابط.","why":"fetch تأخذ الطريقة في كائن الخيارات. المفتاح الواحد خيار في تحديد الأنواع، لا متطلّب وقت التشغيل."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order = { id: number; status: OrderStatus; totalCents: number };\ntype CancelledOrder = { id: number; status: 'cancelled'; cancelReason: string };\ntype Pageابنِ الدالة call محدَّدة الأنواع في Cartwheel.
'POST /orders/:id/cancel' إلى Routes: مدخله { id: number; reason: string } ومخرجه CancelledOrder.call generic على اسم المسار، بحيث يُبحث عن نوع input ونوع القيمة المحلولة في Routes. اختبارات الأنواع تُظهر ما يتوقّعه المستدعون: بلا وسائط نوع، وبلا تحويلات.:param في المسار بقيمة المدخل المطابقة، وأرسل الحقول المتبقّية كجسم للطلبات غير GET. يجب أن ترسل call('POST /orders/:id/cancel', { id: 7, reason: 'Late' }) الطلب POST /orders/7/cancel بالجسم {"reason":"Late"}.call<R extends keyof Routes>(route: R, input: Routes[R]['input']): Promise<Routes[R]['output']>.","داخل الدالة، عامل input كـ Record<string, unknown> بتحويل واحد مشروح بتعليق، وحوّل نتيجة الـ transport إلى Routes[R]['output'] مرة واحدة.","template.replace(/:(\\w+)/g, (_, name) => …) تعطيك اسم كل معامل؛ انسخ المدخل بـ { ...values } واحذف (delete) الأسماء التي استخدمتها، فيكون المتبقّي هو الجسم."],"explanation":"لـ R موقع استنتاج واحد، هو نص المسار، وقيده يُبقيه مفتاحًا حرفيًا. وكل نوع آخر وصولٌ بالفهرس على Routes، فإضافة endpoint تغيير بسطر واحد في الخريطة، ويُفحص كل مستدعٍ مقابلها. التحويلان يعيشان داخل call، موثّقين، بدل أن يكونا في كل موضع استدعاء. ولاحظ أن نوع المخرج ما زال ادّعاءً بشأن الخادم: الـ transport المزيّف يُعيد ما تعد به الخريطة، أما الحقيقي فلا يمكن الوثوق به دون تحقّق.
GET /orders/1042","post-body":"مسار الإلغاء يرسل إلى /orders/7/cancel والجسم فيه الحقول المتبقّية فقط"}},"words":656,"readMinutes":4}