TypeScript Academy · درس

تعريف أجهزة التوجيه والإجراءات

ابنوا الاستعلامات والطفرات مع التحقق من المدخلات

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

تهيئة tRPC

تبدأ كل واجهة خلفية مبنية باستخدام tRPC بإنشاء مثيل باستخدام initTRPC. ويعيد هذا المثيل منشئات للموجّهات والإجراءات. وعادةً ما تنشئ هذا المثيل مرة واحدة وتصدّر الأجزاء التي تحتاج إليها.

import { initTRPC } from '@trpc/server';

const t = initTRPC.create();
export const router = t.router;
export const publicProcedure = t.procedure;

إجراء أول

الإجراء هو نقطة نهاية واحدة لواجهة API. وأبسط إجراء هو استعلام يعيد قيمة. يعرّف publicProcedure.query نقطة نهاية قابلة للقراءة من دون مدخلات.

import { router, publicProcedure } from './trpc';

const appRouter = router({
  health: publicProcedure.query(() => 'ok'),
});

التحقق من المدخلات

تعلن الإجراءات عن مدخلاتها باستخدام أداة تحقق، وغالبًا ما تكون مخطط zod. ويؤدي .input(schema) إلى التحقق في وقت التشغيل واستدلال نوع المدخلات للمحلّل والعميل معًا.

import { z } from 'zod';

const greet = publicProcedure
  .input(z.object({ name: z.string() }))
  .query(({ input }) => 'Hello, ' + input.name);

قراءة المدخلات

داخل المحلّل، تكون المدخلات التي تم التحقق منها متاحة باسم input، ويكون نوعها مستدلًا بالكامل من المخطط. لا حاجة إلى تحويل نوع يدوي؛ إذ يستدل كل من zod وtRPC على البنية معًا.

const byId = publicProcedure
  .input(z.object({ id: z.number() }))
  .query(({ input }) => {
    // input.id is number
    return { id: input.id, name: 'Alice' };
  });

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

استخدم .mutation للعمليات التي تغيّر البيانات. وتكون بنيتها مماثلة لبنية الاستعلام، لكنها تشير إلى عملية كتابة، مما يؤثر في التخزين المؤقت للعميل وطريقة HTTP.

const createUser = publicProcedure
  .input(z.object({ name: z.string() }))
  .mutation(({ input }) => {
    return { id: 1, name: input.name };
  });

بناء موجّه التطبيق

اجمع الإجراءات في موجّه بتمرير كائن إلى router(...). ويصبح كل مفتاح اسم إجراء قابلًا للاستدعاء. ويمثل appRouter واجهة API الكاملة الخاصة بك.

const appRouter = router({
  greet,
  byId,
  createUser,
});

الموجّهات المتداخلة

تتداخل الموجّهات لتنظيم واجهات API الكبيرة. ويمكن أن تكون إحدى قيم كائن الموجّه موجّهًا بحد ذاته، ما ينتج عنه استدعاءات ضمن مساحة أسماء مثل user.byId.

const userRouter = router({ byId, createUser });

const appRouter = router({
  user: userRouter,
  greet,
});
// call paths: user.byId, user.createUser, greet

تصدير نوع الموجّه

أهم تصدير على الإطلاق هو نوع الموجّه. وسيستورده العميل ليحصل على أمان كامل للأنواع. صدّر القيمة لمحوّل الخادم، والنوع للعميل.

export const appRouter = router({ user: userRouter });
export type AppRouter = typeof appRouter;

إرفاق محوّل

لإتاحة الموجّه عبر HTTP، أرفق محوّلًا. يوفر tRPC محوّلات لـ Node المستقل وExpress وNext.js وFetch وغيرها. ويحوّل المحوّل الطلبات الواردة إلى استدعاءات إجراءات.

import { createHTTPServer } from '@trpc/server/adapters/standalone';

createHTTPServer({ router: appRouter }).listen(3000);

تنظيم الملفات

من التنظيمات الشائعة: ملف trpc.ts يضم initTRPC وrouter/publicProcedure المصدّرين، وموجّهات الميزات في ملفاتها الخاصة، وappRouter جذر يؤلفها معًا. ويساعد إبقاء initTRPC في مكان واحد على تجنب إنشاء مثيلات متعددة.

// trpc.ts: initTRPC.create(), export router + publicProcedure
// routers/user.ts: userRouter
// router.ts: appRouter = router({ user: userRouter })

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

بما أن .input(schema) يتحقق من المدخلات ويستدل على نوعها في الوقت نفسه، فإنك تكتب المخطط مرة واحدة وتحصل على حارس في وقت التشغيل ونوع ثابت. وسيرى العميل المدخلات التي يتوقعها كل إجراء بالضبط، والمشتقة من هذه المخططات.

const search = publicProcedure
  .input(z.object({ q: z.string(), page: z.number().optional() }))
  .query(({ input }) => ({ q: input.q, page: input.page ?? 1 }));

تحقق سريع

اختبر فهمك للموجّهات والإجراءات.

مراجعة

لقد بنيت واجهة خلفية باستخدام tRPC.

ينتج initTRPC.create() منشئي router وprocedure.
يتحقق .input(schema) من المدخلات ويستدل على نوعها.
تقرأ .query البيانات، وتكتب .mutation البيانات.
ألّف الإجراءات في appRouter وصدّر type AppRouter = typeof appRouter.

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

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

هل درس «تعريف أجهزة التوجيه والإجراءات» مجاني؟

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

ماذا ستتعلم في «تعريف أجهزة التوجيه والإجراءات»؟

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

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

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

كم من الوقت يستغرق درس «تعريف أجهزة التوجيه والإجراءات»؟

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

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

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

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

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