بنية tRPC
تعرّفوا إلى كيفية إزالة tRPC لتكرار مخطط API
بنية tRPC درس مجاني في TypeScript Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في TypeScript Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة TypeScript Academy 4 دروس في المجموع.
مشكلة البداية إلى النهاية
في تطبيق ويب نموذجي، يعرّف الخادم واجهة API ويستدعيها العميل. ومن الصعب إبقاء أنواعهما متزامنة: فإذا غيّر الخادم حقلًا، يتعطّل العميل بصمت أثناء التشغيل. يحل tRPC هذه المشكلة من خلال مشاركة الأنواع مباشرةً، من دون توليد شيفرة.
// Server: returns { id: number; name: string }
// Client: must know that shape exactly
// Without sync: runtime errors when they driftما هو tRPC
tRPC مكتبة لبناء واجهات API مكتوبة بالكامل بالأنواع في TypeScript. يعرّف الخادم الإجراءات؛ ويستدعيها العميل كما لو كانت دوال محلية، مع إكمال تلقائي كامل وفحص للأنواع مستنتج من شيفرة الخادم.
// Client call looks like a local function:
// const user = await client.user.byId.query(1);
// user is typed automatically from the serverمن دون توليد شيفرة
بخلاف مسارات عمل GraphQL أو OpenAPI، لا يحتاج tRPC إلى خطوة لتوليد الشيفرة. لا يوجد ملف مخطط يجب ترجمته، ولا عميل مولَّد. تنتقل الأنواع من الخادم إلى العميل اعتمادًا على استدلال TypeScript فقط أثناء الترجمة.
// No .graphql files, no generated SDK
// Just import a type from the server packageالموجّه هو العقد
المكوّن الأساسي في tRPC هو الموجّه. وهو شجرة من الإجراءات، مثل الاستعلامات وعمليات التغيير. ويُعد كائن الموجّه على الخادم، وبالتحديد نوعه المستنتج، المصدر الوحيد للحقيقة الذي تتم مشاركته مع العميل.
// appRouter (server) defines every procedure
// type AppRouter = typeof appRouter is the contractكيفية مشاركة الأنواع
يصدّر الخادم نوع الموجّه الخاص به فقط، وليس التنفيذ. ويستورد العميل ذلك النوع ويستخدمه لتحديد نوع عميل وكيل. لا تُرسل أي شيفرة من الخادم إلى المتصفح؛ بل الأنواع فقط، التي تُحذف في وقت البناء.
// server.ts
export type AppRouter = typeof appRouter;
// client.ts
import type { AppRouter } from '../server';الاستعلامات وعمليات التغيير
تأتي الإجراءات في نوعين رئيسيين. يقرأ الاستعلام البيانات ويكون عادةً قابلًا للتكرار بأمان. أما عملية التغيير فتعدّل البيانات. وتنعكس هذه التفرقة على التخزين المؤقت ودلالات HTTP، كما تحدد طريقة استدعاء العميل لها.
// client.user.list.query() -> read
// client.user.create.mutate(...) -> writeوقت التشغيل مقابل الأنواع
لدى tRPC طبقتان. في وقت التشغيل، تكون الاستدعاءات بتنسيق JSON عبر HTTP ويعالجها محوّل. وفي وقت الترجمة، يضمن النوع المشترك AppRouter التحقق الكامل من كل استدعاء. وقت التشغيل بسيط؛ أما القيمة فتكمن في أمان الأنواع.
// Runtime: POST /trpc/user.byId body: {"input":1}
// Types: client.user.byId.query(1) is checked end to endلماذا يتفوق استدلال الأنواع على توليد الشيفرة
بما أن الأنواع مستدلّة، لا توجد خطوة مزامنة يمكن نسيانها. عدّل إجراءً وستعكس التغييرات فورًا على العميل، مع ظهور خطوط حمراء متموجة حيث لم تعد الاستدعاءات متطابقة. وتكون الملاحظات فورية وتظهر في محررك.
// Add a required input field on the server
// -> every client call missing it becomes a type errorأين يناسب tRPC
يتألق tRPC في مستودعات monorepo المكتوبة بالكامل بلغة TypeScript، حيث يشترك العميل والخادم في قاعدة شيفرة واحدة، مثل تطبيقات Next.js. لكنه لا يناسب واجهات API العامة التي تستهلكها لغات أخرى؛ ففي هذه الحالة ستظل بحاجة إلى مخطط محايد اللغة مثل OpenAPI أو GraphQL.
// Great: Next.js app, shared types, internal API
// Not ideal: public API for non-TS consumersالصورة العامة
التدفق هو: تعريف الإجراءات على موجّه، وتصدير نوع الموجّه، وإرفاق محوّل HTTP، وإنشاء عميل محدد الأنواع من ذلك النوع. يخضع كل استدعاء للتحقق مقارنةً بعقد الخادم دون أي شيفرة مولّدة. وستبني الدروس التالية كل جزء من هذه الأجزاء.
// Roadmap:
// 1. initTRPC + procedures + appRouter
// 2. export AppRouter, create typed client
// 3. context + middleware for authثق بالمترجم
يتمثل التحول في طريقة التفكير في أن عقد API يوجد في الأنواع التي يفرضها المترجم، وليس في التوثيق أو التحقق في وقت التشغيل وحده. إذا نجحت الشيفرة في الترجمة، فهذا يعني أن العميل والخادم متفقان. وهذا الضمان هو المقصود بعبارة "أمان الأنواع من الطرف إلى الطرف".
// If client.ts compiles, it matches the current server.تحقق سريع
اختبر فهمك لبنية tRPC.
مراجعة
لقد تعلمت نموذج tRPC.
- الموجّه هو العقد؛ ونوعه هو المصدر الوحيد للحقيقة.
- يصدّر الخادم نوع
AppRouterفقط، وليس الشيفرة. - تقرأ الاستعلامات البيانات، وتكتب عمليات التغيير البيانات؛ أما وقت التشغيل فيعتمد على JSON عبر HTTP.
- يأتي أمان الأنواع من الاستدلال، من دون خطوة لتوليد الشيفرة.
التالي: تعريف الموجّهات والإجراءات.
الأسئلة الشائعة
هل درس «بنية tRPC» مجاني؟
نعم — نص درس «بنية tRPC» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة TypeScript Academy، انتقل إلى CoddyKit PRO. تتضمن دورة TypeScript Academy 4 دروس في المجموع.
ماذا ستتعلم في «بنية tRPC»؟
تعرّفوا إلى كيفية إزالة tRPC لتكرار مخطط API تتمرن على TypeScript Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ TypeScript Academy؟
لا تُشترط خبرة سابقة. TypeScript Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.
كم من الوقت يستغرق درس «بنية tRPC»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس TypeScript Academy هذا؟
نعم. كل درس في TypeScript Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.