TypeScript Academy · درس

استنتاج الأنواع بين العميل والخادم

احصلوا على عملاء محددين الأنواع بالكامل من دون توليد التعليمات البرمجية

استنتاج الأنواع بين العميل والخادم درس مجاني في TypeScript Academy على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في TypeScript Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

مشاركة نوع الموجّه

يحصل العميل على أمان الأنواع باستيراد نوع موجّه الخادم. وهذا استيراد للنوع فقط: لا يتم تشغيل أي شيء من الخادم في العميل؛ بل يعبر العقد الثابت الحدود فقط.

import type { AppRouter } from '../server/router';
// type-only import - erased at build time

إنشاء عميل محدد الأنواع

استخدم createTRPCClient، أو صيغة proxy، مع تحديد AppRouter كمعامل نوع. وسيحاكي كائن العميل بعد ذلك بنية موجّه الخادم، مع إكمال تلقائي كامل لكل إجراء.

import { createTRPCClient, httpBatchLink } from '@trpc/client';

const client = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: 'http://localhost:3000' })],
});

استدعاء الإجراءات

تحاكي الاستدعاءات شجرة الموجّه. إذ تصل إلى الإجراء المتداخل user.byId عبر client.user.byId، ثم تستدعي عليه .query أو .mutate. وتكون المدخلات والمخرجات محددة الأنواع من الخادم.

const user = await client.user.byId.query({ id: 1 });
// user is typed exactly as the server resolver returns

المدخلات المستدلّة

يعرف العميل مدخلات كل إجراء من مخطط الخادم. وتمرير بنية غير صحيحة يؤدي إلى خطأ في الترجمة قبل تشغيل التطبيق أصلًا.

await client.user.byId.query({ id: 1 });   // ok
// await client.user.byId.query({ id: 'x' }); // error: id must be number
// await client.user.byId.query({});          // error: id is required

المخرجات المستدلّة

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

const u = await client.user.byId.query({ id: 1 });
const name: string = u.name; // ok if server returns name: string

عمليات التغيير على العميل

تُستدعى عمليات التغيير باستخدام .mutate. وينطبق الاستدلال نفسه: يتحقق المخطط من نوع المدخلات، ويحدد المحلّل نوع المخرجات.

const created = await client.user.create.mutate({ name: 'Bea' });
// created is typed from the create resolver's return

تدفق الاستدلال

تتبّع كيفية انتقال النوع: يستدل مخطط zod على نوع المدخلات في الخادم، ويستدل نوع إرجاع المحلّل على نوع المخرجات، ثم يلتقط typeof appRouter كليهما في AppRouter، ويطابق العميل ذلك النوع مع أساليب قابلة للاستدعاء. وينتشر أي تغيير تلقائيًا عبر النظام.

// schema -> input type
// resolver -> output type
// appRouter -> AppRouter (both captured)
// client<AppRouter> -> typed calls

استدلال الأنواع المساعدة

يوفر tRPC أدوات مساعدة لاستخراج أنواع المدخلات والمخرجات وإعادة استخدامها، مثل استخدامها في مكونات React. ويمنحك inferRouterInputs وinferRouterOutputs هذه الخرائط انطلاقًا من AppRouter.

import type { inferRouterOutputs } from '@trpc/server';

type Outputs = inferRouterOutputs<AppRouter>;
type User = Outputs['user']['byId'];

ضمان عدم الانحراف

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

// Server renames user.byId -> user.find
// client.user.byId becomes a type error immediately

التجميع والروابط

تضبط مصفوفة links طريقة النقل. إذ يجمع httpBatchLink عدة استدعاءات تُجرى في دورة التنفيذ نفسها في طلب HTTP واحد، مما يقلل عدد الرحلات ذهابًا وإيابًا. وهذا تحسين في وقت التشغيل لا يؤثر في الأنواع.

links: [httpBatchLink({ url: '/trpc' })]
// Several .query calls in one tick -> one request

أمان شامل عمليًا

والنتيجة هي أنك تستدعي client.user.byId.query(...) كما لو كانت دالة محلية، مع إكمال تلقائي للمدخلات، والتحقق من الوسائط، ونتيجة محددة النوع، وكل ذلك مشتق من شيفرة الخادم دون ملفات مولّدة. هذا هو أمان الأنواع من الطرف إلى الطرف الذي يحققه الاستدلال.

const u = await client.user.byId.query({ id: 7 });
console.log(u.name); // fully typed, no codegen

تحقق سريع

اختبر فهمك لاستدلال الأنواع بين العميل والخادم.

مراجعة

لقد استهلكت واجهة API مبنية باستخدام tRPC مع أمان كامل للأنواع.

استورد AppRouter باعتباره استيرادًا للنوع فقط.
تحاكي createTRPCClient<AppRouter> شجرة الموجّه.
يُستدل على المدخلات والمخرجات من مخططات الخادم ومحلّلاته.
لا يمكن أن ينحرف العميل عن الخادم أو الخادم عن العميل؛ فالمترجم يفرض العقد.

التالي: السياق والبرمجية الوسيطة للمصادقة.

الأسئلة الشائعة

هل درس «استنتاج الأنواع بين العميل والخادم» مجاني؟

نعم — نص درس «استنتاج الأنواع بين العميل والخادم» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة TypeScript Academy، انتقل إلى CoddyKit PRO. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

ماذا ستتعلم في «استنتاج الأنواع بين العميل والخادم»؟

احصلوا على عملاء محددين الأنواع بالكامل من دون توليد التعليمات البرمجية تتمرن على TypeScript Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ TypeScript Academy؟

لا تُشترط خبرة سابقة. TypeScript Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «استنتاج الأنواع بين العميل والخادم»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس TypeScript Academy هذا؟

نعم. كل درس في TypeScript Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى TypeScript Academy