المشكلة التي يحلّها tRPC

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

ويتحول تغيير اسم حقل على الخادم إلى خطأ صامت أثناء التشغيل على العميل.

تحل GraphQL مشكلة انجراف الأنواع عبر إنشاء أنواع TypeScript من المخطط باستخدام أدوات مثل graphql-codegen. وينجح هذا النهج جيدًا، لكنه يضيف تعقيدًا يتمثل في لغة استعلام منفصلة (GraphQL SDL)، وخطوة لإنشاء الكود ضمن مسار البناء، وأدوات لإدارة المخطط.

بالنسبة إلى الفرق المستثمرة أصلًا في GraphQL، يُعد codegen الحل المناسب. أما الفرق التي تريد أمان الأنواع من دون أعباء GraphQL، فتقدم tRPC بديلًا.

يتميز نهج tRPC ببساطته الجذرية: عرّف إجراءات API على الخادم باعتبارها دوال TypeScript، وصدّر نوع الموجّه، ثم استورد ذلك النوع على العميل. لا حاجة إلى إنشاء كود. ولا حاجة إلى لغة مخطط منفصلة.

ويفرض مص compiler TypeScript نفسه العقد بين العميل والخادم أثناء البناء.

يتطلب tRPC أن يشارك الخادم والعميل الأنواع عبر عمليات استيراد TypeScript. ويعمل هذا طبيعيًا في مستودع أحادي (Turborepo وNx وpnpm workspaces)، حيث يكون الخادم والعميل حزمتين منفصلتين يمكنهما الاستيراد من بعضهما.

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

على الخادم، تعرّف موجّهًا وتصدّر نوعه: export type AppRouter = typeof appRouter. وعلى العميل، تستورد ذلك النوع وتنشئ عميلًا مقيّدًا بالأنواع: createTRPCReact(). يعرف العميل بدقة الإجراءات الموجودة وأنواع مدخلاتها ومخرجاتها.

ويؤدي تغيير اسم إجراء على الخادم فورًا إلى ظهور خطأ TypeScript على العميل.

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

يُعد هذا التحسن في تجربة المطور الميزة الأكثر إشادةً في tRPC عمليًا.

تستخدم tRPC بروتوكول HTTP افتراضيًا كوسيلة نقل. ويكون كل استدعاء لإجراء طلب HTTP. كما تدعم tRPC WebSockets للاشتراكات. وتُعد وسيلة النقل تفصيلًا من تفاصيل التنفيذ؛ إذ تظل واجهة API للعميل متطابقة بغض النظر عن وسيلة النقل.

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

تعمل tRPC كبرمجية وسيطة في Express وFastify وHono. وبالنسبة إلى Next.js، تتكامل عبر معالجات مسارات API. وتجمع أداة البدء create-t3-app (T3 Stack) بين tRPC وPrisma وNextAuth وTailwind في قالب Next.js متكامل.

تُعد T3 Stack نقطة البدء الأكثر شيوعًا مع tRPC، كما تعرض أنماطًا جاهزة للاستخدام في بيئة الإنتاج.

هناك نهج آخر لبناء REST آمن من ناحية الأنواع، وهو تعريف مخططات Zod، وإنشاء مواصفة OpenAPI تلقائيًا، ثم إنشاء أنواع TypeScript من المواصفة. ويوفر هذا النهج عقد API يمكن لعملاء غير مكتوبين باستخدام TypeScript استهلاكه.

تتميز tRPC بالبساطة لكنها محصورة في TypeScript. أما OpenAPI+Zod فيضيف تعقيدًا لكنه ينتج عقد API عامة. اختر tRPC للاتصال الداخلي بين TypeScript وTypeScript، واختر OpenAPI لواجهات API العامة.

لا تُعد tRPC بديلًا عن REST عندما تحتاج إلى API عامة تستهلكها جهات خارجية، أو عملاء للهواتف المحمولة غير مكتوبين باستخدام TypeScript، أو شركاء يحتاجون إلى عقد ثابت ذي إصدارات. فهي مخصصة تحديدًا لمستودعات TypeScript الأحادية التي تتطلب أمان الأنواع عبر كامل المكدس.

يساعد فهم هذا النطاق على تجنب اعتماد tRPC في سياقات تكون فيها REST أو GraphQL أنسب.

يؤدي تشغيل npm create t3-app@latest إلى إنشاء هيكل مشروع Next.js مع إعداد tRPC وPrisma وNextAuth.js وTailwind CSS وTypeScript مسبقًا. يوضّح الرمز المُنشأ بنية الموجّه وإنشاء السياق وإعداد العميل.

تُعد دراسة هذا الهيكل المُنشأ أسرع طريقة لفهم كيفية تكامل جميع مكوّنات tRPC في تطبيق حقيقي.

كيف يشارك tRPC الأنواع بين الخادم والعميل من دون توليد التعليمات البرمجية؟

تحل tRPC مشكلة انحراف الأنواع بين عميل TypeScript وخادمه عبر مشاركة نوع TypeScript الخاص بالموجّه مباشرةً من خلال الاستيراد، مما يلغي توليد التعليمات البرمجية. وتعمل tRPC في المستودعات الأحادية، كما تتكامل مع Next.js وExpress وFastify وHono. وتُعد حزمة T3 (create-t3-app) نقطة البداية القياسية للتطبيقات الإنتاجية.

تقتصر tRPC على TypeScript، وتناسب تطبيقات full-stack الداخلية بدرجة أكبر من واجهات API العامة.