TypeScript / المتقدم / الدرس 13
تصميم المكتبات العامة وإصداراتها
صمّم عقدًا للمستهلك بإنشاء مضبوط وفشل صريح وتصريحات دقيقة وسياسة توافق تتجاوز نجاح بناء محلي.
في هذه الصفحة
أهداف الدرس
- اختيار عقود الملكية والتعديل والخطأ العامة.
- استخدام إنشاء مفحوص دون علامات قائمة على التأكيد.
- مراجعة تغييرات التصريحات والحزم من شيفرة المستهلك.
النوع العام التزام للمستدعي
توضح المكتبة المدخلات وملكية النتيجة والتعديل والتوقيت والأخطاء والتوافق. تصف التواقيع جزءًا منها فقط. تقيد readonly مسارًا وقد تشارك تخزينًا متغيرًا. يحتاج المستهلك معرفة فورية الرد أو حفظه. تجنب تصدير كل مساعد أو اتحاد داخلي كي لا يتحول التغيير إلى كسر عام. سمّ النتائج والأخطاء بالمجال ليفهمها المستهلك دون تفكيك نوع معقد أو قراءة التنفيذ.
إثبات الصلاحية بمسار إنشاء فعلي
يسمح الصنف بالإنشاء عبر أسلوب فحص ساكن في TypeScript المفحوصة. المنشئ private قيد ترجمة، ولـ#value خصوصية JavaScript فعلية. يفحص المصنع الصحيح الآمن والمجال قبل الإنشاء ويعلن الرفض بدل علامة بتأكيد. تحتاج مداخل JavaScript الفحص نفسه؛ فلا تعتبر خصوصية المنشئ حد أمان. المصنع المفحوص هو المسار المدعوم هنا.
export {};
class Count {
#value: number;
private constructor(value: number) { this.#value = value; }
static create(value: number): Count | undefined {
return Number.isSafeInteger(value) && value >= 0 && value <= 1000 ? new Count(value) : undefined;
}
value(): number { return this.#value; }
}
console.log(Count.create(42)?.value(), Count.create(1001) === undefined);
42 true
تجتاز اثنتان وأربعون القواعد وتُرفض ألف وواحد قبل إنشاء الكائن.
الفشل المتوقع يستحق نتيجة منظمة
يفصل اتحاد نتيجة موسوم الفشل الطبيعي من الاستثناء. تقبل الدالة نصين فعليين وتعيد فئة unsupported للباقي. وثّق النتائج والرمي إذا اختلفا بين العمليات. قد تؤثر إضافة بديل في المستهلك الشامل، ولا تجعل الرسالة وسيلة التصنيف الوحيدة. يبرر المحلل قيمة الوضع الحرفية دون تأكيد، وتحتاج الكائنات unknown فحصًا قبل حد النص.
export {};
type Mode = "fast" | "safe";
type Result<T> = { ok: true; value: T } | { ok: false; error: "unsupported" };
function parseMode(text: string): Result<Mode> {
if (text === "fast" || text === "safe") { return { ok: true, value: text }; }
return { ok: false, error: "unsupported" };
}
console.log(JSON.stringify(parseMode("safe")));
console.log(JSON.stringify(parseMode("other")));
{"ok":true,"value":"safe"}
{"ok":false,"error":"unsupported"}
يصير النص المقبول Mode مفحوصة ويعطي الباقي بديل الفشل الموثق.
نشر تصريحات تطابق الحزمة الفعلية
تصف التصريحات المولدة الواجهة ويجب أن توجّه بيانات الحزمة إلى مدخلي JavaScript والأنواع الصحيحين. اختبر ESM وCommonJS إذا وعدت بهما. يكشف مستهلك الناتج المحزم ملفات مفقودة أو exports خاطئة أو مسارات مصدر. وثّق الحد الأدنى للمترجم والبيئة مستقلين لاختلاف التوافق. تجنب أنواع اعتماديات داخلية غير مستقرة؛ وقد يقلل النوع العام الصغير الترابط وكلفة الفحص.
تقييم التغيير بأثره الملحوظ
قد تكسر تغييرات المعامل والرد والغياب والتحميل والاستنتاج والاتحاد المستهلك رغم نجاح المصدر. ويهم تغيير التعديل والبدائل والتسلسل والأخطاء. احفظ تجارب مستهلكين وفحص تصريحات مع التنفيذ. قد يكشف التحديث عيبًا أو يغير استنتاجًا فراجع قبل رفع الأساس. لا يضمن رقم الإصدار التوافق؛ وضّح الإهمال والترحيل واحفظ القديم إذا ظل آمنًا ومقصودًا.
الأخطاء الشائعة وإصلاحها
معاملة منشئ private كصلاحية أمان.
- لماذا يحدث؟
- خُلط قيد الترجمة بحد الثقة.
- كيف تصلحه؟
- افرض الفحوص الفعلية بالمداخل العامة.
- كيف تتجنب تكراره؟
- ميّز خصوصية TypeScript وحقول JavaScript الخاصة.
حزمة تصريحات بلا تنفيذ قابل للتحميل.
- لماذا يحدث؟
- خُلط نشر الأنواع بنشر الملفات التنفيذية.
- كيف تصلحه؟
- افحص تصدير JavaScript والتصريحات معًا.
- كيف تتجنب تكراره؟
- اختبر بمستهلك حزمة منفصل.
بديل اتحاد جديد يكسر مستدعيًا شاملًا.
- لماذا يحدث؟
- كانت الشمولية ضمن العقد العام.
- كيف تصلحه؟
- خطط توافقًا أو ترحيلًا صريحًا.
- كيف تتجنب تكراره؟
- راجع الأنواع من الاستدعاءات الخارجية.
اختبر فهمك
1. صنّف Count.create(0) وCount.create(2.5) وCount.create(1000) وحدّد ما يفرض المجال.
اعرض الحل المشروح
ينشئ الصفر والألف قيمتين ويعطي الكسر undefined. تفرض Number.isSafeInteger والمقارنات المجال فعليًا لا المعلمة أو private وحدهما. عالج الرفض قبل الاعتماد على كائن واختبر الطرفين والكسر.
2. تغير مكتبة parseMode لترمي عند غير المدعوم بدل نتيجة خطأ. لماذا لا يثبت نجاحها المتطابق التوافق؟
اعرض الحل المشروح
لا يتلقى من يعالج ok بديل الفشل وقد يصادف استثناء غير ملتقط. قناة الفشل سلوك عام. أضف اختبارات رفض للمستهلك وقيّم التغيير بسياسة التوافق وترحيل مقصود؛ فلا تكشفه مدخلات safe وحدها.
أهم ما تعلمته
- صمّم السلوك العام وراء التواقيع.
- افحص الإنشاء وأظهر الفشل.
- اختبر التصريحات والملفات كمستهلك.