TypeScript Academy · درس

رسائل الأخطاء في DSL على مستوى النوع

اعرضوا أخطاء تجميع مفيدة لمستخدمي DSL

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

رسائل مفيدة في DSLs على مستوى الأنواع

أصعب جانب في DSL على مستوى الأنواع هو جعل حالات الفشل مقروءة. فأخطاء never الخام أو أخطاء "not assignable" تربك المستخدمين. نعرض أخطاء وصفية باستخدام أنواع أخطاء ذات وسوم ورسائل never مصاغة بعناية.

مشكلة never

عندما يفشل التحقق بتحويل النتيجة إلى never، يقول المترجم "Argument of type X is not assignable to never"، وهذا لا يخبر المستخدم بالسبب. يمكننا تقديم نتيجة أفضل.

أنواع الأخطاء ذات الوسوم

بدلًا من استخدام never عادي، أعد نوع خطأ ذي بنية مميزة يحمل سلسلة رسالة مقروءة للبشر ضمن نوعه.

type TypeError<Msg extends string> = {
  readonly __error: Msg;
};

type E = TypeError<"Column 'foo' does not exist">;

إرجاع الأخطاء من التحقق

يعيد أداة التحقق إما نوع القيمة الصالحة أو خطأ ذا وسم يصف المشكلة. أما فحص «يحتوي على نقطة» فهو نمط قالب حرفي، وتُستخدم backticks في الشيفرة الحقيقية؛ ونستخدم HasDot للدلالة عليه.

// HasDot<S> is the backtick pattern: any text, ".", any text.

type Validate<S extends string> =
  S extends HasDot
    ? S
    : TypeError<"Path must contain a dot, e.g. user.name">;

إجبار الخطأ على الظهور

قيّد المعلمة بحيث يؤدي تمرير أي قيمة غير قابلة للإسناد إلى وسم الخطأ إلى عرض الرسالة. وسيظهر نوع الخطأ مباشرةً في مخرجات المترجم.

declare function path<S extends string>(
  p: Validate<S> extends TypeError<infer M> ? TypeError<M> : S
): void;

path("oops");
// Error message includes: __error: "Path must contain a dot..."

التمييز بين أخطاء متعددة

تعيد حالات الفشل المختلفة رسائل مختلفة، ولذلك يحصل المستخدمون على إرشادات محددة بدلًا من رفض عام واحد. وHasDot هو مرة أخرى نمط قالب حرفي باستخدام backtick لـ«يحتوي على نقطة».

type Check<S extends string> =
  S extends "" ? TypeError<"Path cannot be empty">
  : S extends HasDot ? S
  : TypeError<"Missing dot separator">;

never مع لمسة مختلفة

تربط تقنية أخرى موضع قيمة برسالة حرفية بحيث تكشف معاينة النوع الرسالة. وتجمع نوع القيمة المخالفة مع كائن ذي تسمية.

type Invalid<M extends string> = { error: M } & never;
// using never keeps it unassignable while the label hints the cause

الأخطاء في DSLs ذات الواجهة المتسلسلة

في DSL متسلسل، اجعل الخطوة التالية غير الصالحة تعيد نوعًا ذا وسم خطأ بدلًا من مرحلة صالحة، حتى يعرض المحرر الرسالة في موضع الخطأ مباشرةً.

interface Stage {
  // calling done() before where() yields a labeled error
  done(): TypeError<"Call .where() before .done()">;
}

إبقاء الرسائل قصيرة

تؤدي أنواع الرسائل الطويلة إلى تضخيم مخرجات المترجم وإبطاء أدوات التطوير. فضّل العبارات الموجزة والقابلة للتنفيذ. أدرج الرمز المخالف عندما تكون كلفة ذلك منخفضة، لكن تجنب الاستبدالات النصية الضخمة.

اختبار أخطائك

اكتب اختبارات على مستوى الأنواع تؤكد ظهور وسم الخطأ للمدخلات المعروفة بأنها غير صالحة، حتى لا تؤدي إعادة الهيكلة إلى تدهور تجربة المطور بصمت.

type Expect<T extends true> = T;
type _t = Expect<Validate<"oops"> extends TypeError<any> ? true : false>;

لماذا يهم هذا

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

اختبار سريع

تأكد من فهمك لرسائل الأخطاء على مستوى الأنواع.

مراجعة

لجعل DSLs على مستوى الأنواع سهلة الاستخدام، استبدل never المجرد بأنواع أخطاء ذات وسوم تتضمن رسائل مقروءة. تعيد أدوات التحقق إما النوع الصالح أو وسم خطأ محددًا؛ ويؤدي تقييد المعلمات إلى إظهار الرسالة في مخرجات المترجم. اجعل الرسائل قصيرة واختبرها.

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

هل درس «رسائل الأخطاء في DSL على مستوى النوع» مجاني؟

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

ماذا ستتعلم في «رسائل الأخطاء في DSL على مستوى النوع»؟

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

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

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

كم من الوقت يستغرق درس «رسائل الأخطاء في DSL على مستوى النوع»؟

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

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

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

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

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