TypeScript Academy · درس

البرمجيات الوسيطة والسياق

أضيفوا المصادقة والسياق المشترك إلى الإجراءات

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

ما هو السياق

يحمل كل طلب من tRPC سياقًا: بيانات مشتركة متاحة لجميع الإجراءات، مثل عميل قاعدة البيانات والطلب والمستخدم الحالي. وتنشئ هذا السياق مرة واحدة لكل طلب باستخدام الدالة createContext.

export async function createContext({ req }: { req: Request }) {
  const token = req.headers.get('authorization');
  const user = await getUserFromToken(token);
  return { user };
}

تحديد نوع السياق

يستدل tRPC على نوع السياق من createContext ويمرره عبر كل إجراء. وتُهيّئ المثيل باستخدام نوع السياق هذا، بحيث ترى المحلّلات ctx محدد النوع بشكل صحيح.

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

type Context = Awaited<ReturnType<typeof createContext>>;
const t = initTRPC.context<Context>().create();

قراءة ctx في محلّل

يتاح السياق داخل أي إجراء باسم ctx ويكون محدد النوع بالكامل. ويقرأ أحد الإجراءات هنا المستخدم الحالي من السياق.

const me = t.procedure.query(({ ctx }) => {
  // ctx.user is typed from createContext
  return ctx.user;
});

ما هي البرمجية الوسيطة

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

const logger = t.middleware(async ({ path, next }) => {
  console.log('calling', path);
  return next();
});

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

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

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

const isAuthed = t.middleware(({ ctx, next }) => {
  if (!ctx.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next();
});

تضييق نوع السياق باستخدام next

يمكن للبرمجية الوسيطة تحسين نوع السياق بتمرير ctx جديد إلى next. وبعد التحقق من المصادقة، يكون وجود المستخدم مضمونًا، ولذلك نضيّق نوع user من احتمال كونه فارغًا إلى نوع غير فارغ.

const isAuthed = t.middleware(({ ctx, next }) => {
  if (!ctx.user) throw new TRPCError({ code: 'UNAUTHORIZED' });
  return next({ ctx: { user: ctx.user } }); // user now non-null
});

بناء إجراء محمي

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

export const protectedProcedure = t.procedure.use(isAuthed);

const secret = protectedProcedure.query(({ ctx }) => {
  return 'Hello ' + ctx.user.name; // user is guaranteed
});

المتاح للعامة مقابل المحمي

لديك الآن لبنتان أساسيتان: publicProcedure لنقاط النهاية المفتوحة، وprotectedProcedure لنقاط النهاية التي تتطلب المصادقة. ويوثّق اختيار الأساس الصحيح صلاحيات الوصول ويفرضها على مستوى النوع ووقت التشغيل.

const ping = publicProcedure.query(() => 'pong');
const account = protectedProcedure.query(({ ctx }) => ctx.user);

انتشار ctx محدد النوع

ينتشر تضييق السياق؛ فبما أن protectedProcedure يضمن وجود ctx.user، يرى كل محلّل مبني عليه النوع غير الفارغ من دون إعادة التحقق. وتشفّر البرمجية الوسيطة هذا الثابت مرة واحدة.

// In any protectedProcedure resolver:
// ctx.user is User, not User | null

تأليف البرمجيات الوسيطة

تتألف البرمجية الوسيطة بتسلسل استدعاءات .use. ويمكنك تطبيق التسجيل، ثم المصادقة، ثم التحقق من الدور. ويعمل كل منها بالترتيب، كما يمكن لكل منها تضييق السياق أكثر بالنسبة إلى التالي.

const adminProcedure = protectedProcedure.use(({ ctx, next }) => {
  if (ctx.user.role !== 'admin') {
    throw new TRPCError({ code: 'FORBIDDEN' });
  }
  return next();
});

الصورة الكاملة

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

// createContext -> ctx
// middleware -> auth + narrowing
// protectedProcedure -> guaranteed ctx.user
// typed client -> end-to-end safety

تحقق سريع

اختبر فهمك للسياق والبرمجية الوسيطة.

مراجعة

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

تنشئ createContext بيانات مشتركة لكل طلب، ويُحدَّد نوعها عبر initTRPC.context.
تعمل البرمجية الوسيطة قبل المحلّلات لحراسة السياق وتحسين نوعه.
يؤدي تمرير ctx إلى next إلى تضييق نوعه.
يدمج protectedProcedure المصادقة، بحيث تحصل المحلّلات على مستخدم غير فارغ.

لقد أكملت دورة أمان الأنواع من الطرف إلى الطرف.

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

هل درس «البرمجيات الوسيطة والسياق» مجاني؟

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

ماذا ستتعلم في «البرمجيات الوسيطة والسياق»؟

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

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

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

كم من الوقت يستغرق درس «البرمجيات الوسيطة والسياق»؟

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

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

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

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

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