TypeScript Academy · درس

محلل مسارات مصغّر على مستوى النوع

حلّلوا مسارات التوجيه إلى كائنات معلمات محددة الأنواع

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

الهدف

نبني محلّل مسارات يقرأ مسارًا مثل "users/:id/posts/:postId" وينتج كائن معلمات ذي أنواع { id: string; postId: string } بالكامل أثناء الترجمة. وهذا نمط حقيقي تستخدمه أجهزة التوجيه ذات الأنواع.

type Params = ParseRoute<"users/:id/posts/:postId">;
// Goal: { id: string; postId: string }

التعرّف على معلَمة

يكون مقطع المسار معلَمة عندما يبدأ بـ ":". نطابق تلك البادئة باستخدام قالب حرفي ونستنتج اسم المعلَمة بعد النقطتين.

الترميز: تكتب TypeScript الفعلية الأنواع الحرفية للقوالب باستخدام سلاسل محاطة بعلامتي backtick وتحتوي على مواضع بالصيغة dollar-brace. نعرض هذا النمط في هذه المقاطع بصيغة Tpl<...>، مع سرد كل جزء بالترتيب؛ فمثلًا، يظهر قالب backtick المطابق للبادئة الحرفية ثم Rest بالشكل Tpl<'prefix', infer Rest>.

type ParamName<S> = S extends Tpl<':', infer Name> ? Name : never;
// Tpl<...> denotes a backtick template literal type: a colon then Name

type X = ParamName<':id'>;   // 'id'
type Y = ParamName<'users'>; // never

تقسيم المسار

قسّموا المسار أولًا إلى مقاطع عند "/"، مع إعادة استخدام النوع Split. ويكون كل مقطع بعد ذلك إما حرفيًا أو معلَمة.

type Split<S extends string, Sep extends string> =
  S extends Tpl<infer H, Sep, infer T> ? [H, ...Split<T, Sep>] : [S];
// Tpl<H, Sep, T> = a template literal type matching H, then Sep, then T

type Segs = Split<'users/:id', '/'>; // ['users', ':id']

التكرار المباشر للقالب

يمكننا أيضًا تحليل السلسلة الأولية من دون تقسيمها أولًا، وذلك بمطابقة مقطع واحد في كل مرة. طابقوا حتى الفاصل "/" التالي، وتعاملوا مع ذلك المقطع، ثم كرّروا العملية على الباقي.

type ParseRoute<S extends string> =
  S extends Tpl<infer Seg, '/', infer Rest>
    ? SegParam<Seg> & ParseRoute<Rest>
    : SegParam<S>;
// Tpl<Seg, '/', Rest> matches a segment, a slash, then the rest

معلَمة لكل مقطع

يحوّل المساعد مقطعًا واحدًا إلى كائن ذي خاصية واحدة، إذا كان معلَمة، أو إلى كائن فارغ، إذا كان حرفيًا.

type SegParam<S extends string> =
  S extends Tpl<':', infer Name> ? { [K in Name]: string } : {};
// Tpl<':', Name> matches a colon followed by the param name

type X = SegParam<':id'>;   // { id: string }
type Y = SegParam<'posts'>; // {}

الدمج باستخدام التقاطع

يسهم كل مقطع بمعلماته عبر التقاطع. وتختفي الكائنات الفارغة في التقاطع، لذا لا تبقى في النوع النهائي إلا المعلمات الفعلية.

type Params = ParseRoute<"users/:id/posts/:postId">;
// { id: string } & {} & { postId: string } & {}
// = { id: string; postId: string }

تتبّع التحليل

بالنسبة إلى "users/:id/posts/:postId":

المقطع "users" -> {}، ثم التكرار على ":id/posts/:postId"
المقطع ":id" -> { id: string }، ثم التكرار على "posts/:postId"
المقطع "posts" -> {}، ثم التكرار على ":postId"
المقطع ":postId" -> { postId: string }، وهي الحالة الأساسية

type Final = { id: string } & { postId: string };

تنظيف النتيجة

يظهر تقاطع الكائنات بطريقة غير مرتبة. يعمل مساعد «prettify» على تسطيحه إلى نوع كائن واحد واضح باستخدام نوع mapped على مفاتيحه.

type Prettify<T> = { [K in keyof T]: T[K] } & {};

type Clean = Prettify<ParseRoute<"users/:id">>; // { id: string }

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

أدخلوا النوع المحلَّل في دالة حتى يتلقى معالج الطلبات معلمات ذات أنواع صحيحة. ويؤدي تمرير مفتاح خاطئ إلى خطأ في الترجمة.

declare function route<P extends string>(
  path: P,
  handler: (params: Prettify<ParseRoute<P>>) => void
): void;

route("users/:id", p => { const id: string = p.id; });

فائدة المعلمات ذات الأنواع

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

route("users/:userId", p => {
  const u = p.userId; // ok
  // const x = p.id; // error: id does not exist
});

توسيع المحلّل

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

type SegParam2<S extends string> =
  S extends Tpl<':', infer N, '(number)'> ? { [K in N]: number }
  : S extends Tpl<':', infer N> ? { [K in N]: string }
  : {};
// Tpl<...> stands for a backtick template literal type pattern

تحقّق سريع

اختبروا فهمكم لمحلّل المسارات.

مراجعة

بنيتم محلّل مسارات أثناء الترجمة.

طابقوا كل مقطع باستخدام استدلال القوالب الحرفية التكراري.
تتحول مقاطع المعلمات (:name) إلى { name: string }.
تتحول المقاطع الحرفية إلى {} وتختفي في التقاطع.
يسطّح Prettify النتيجة إلى معلمات واضحة.

التالي في الدورة 25: أمان الأنواع من البداية إلى النهاية باستخدام tRPC.

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

هل درس «محلل مسارات مصغّر على مستوى النوع» مجاني؟

نعم — نص درس «محلل مسارات مصغّر على مستوى النوع» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 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