Angular Academy · درس

واجهة API العامة ونقاط الدخول

صمّم واجهة مكتبة واضحة

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

نطاق واجهة البرمجة العامة

ينبغي أن تكشف المكتبة فقط ما يُفترض أن يستخدمه المستهلكون. تمثل واجهة البرمجة العامة مجموعة الصادرات المنتقاة؛ أما كل ما عداها فيبقى داخليًا. في مكتبات Angular، يحدد هذا النطاق الملف public-api.ts.

استخدام public-api.ts كملف تجميعي

يعيد public-api.ts تصدير الرموز التي تريد إتاحتها للمستهلكين. وإذا لم يُصدَّر عنصر من هنا، فإنه يُعد خاصًا فعليًا، حتى لو كان موجودًا في الشيفرة المصدرية.

// projects/ui-kit/src/public-api.ts
export * from './lib/button/button.component';
export * from './lib/theme.service';
// internal helpers are intentionally NOT exported

لماذا نخفي التفاصيل الداخلية

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

تصدير الأنواع والرموز

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

export { ButtonComponent } from './lib/button/button.component';
export type { ButtonVariant } from './lib/button/button.types';
export { THEME_CONFIG } from './lib/theme.tokens';

نقاط الدخول الثانوية

تقسّم المكتبات الكبيرة إلى نقاط دخول ثانوية حتى يستورد المستهلكون ما يحتاجون إليه فقط (لتحسين tree-shaking). على سبيل المثال، ui-kit/testing منفصل عن ui-kit.

import { ButtonComponent } from 'ui-kit';
import { provideUiKitTesting } from 'ui-kit/testing';

إنشاء نقطة دخول ثانوية

نقطة الدخول الثانوية هي مجلد فرعي يحتوي على ملف ng-package.json وملف public-api.ts خاصين به. يكتشفها ng-packagr تلقائيًا ويبنيها كمسار استيراد منفصل.

projects/ui-kit/
  testing/
    ng-package.json   # marks a secondary entry point
    src/public-api.ts

تعيين نقطة الدخول الرئيسية

يشير ملف ng-package.json الخاص بالمكتبة بحقل entryFile إلى public-api.ts، موضحًا للبناء الملف الذي يمثل نطاق الواجهة العامة الرئيسي.

// projects/ui-kit/ng-package.json
{
  "lib": { "entryFile": "src/public-api.ts" }
}

التصميم لتحقيق الاستقرار

تعامل مع واجهة البرمجة العامة باعتبارها عقدًا: إزالة تصدير أو إعادة تسميته تغيير كاسر. أضف الصادرات الجديدة بحرية، لكن أعلن عن إهمال الصادرات قبل إزالتها حتى يتاح للمستهلكين وقت للترحيل.

تجنب الاستيرادات العميقة

بما أن public-api.ts وحده يمثل العقد، يجب ألا يستورد المستهلكون مسارات داخلية عميقة مثل ui-kit/lib/button/internal. ويضمن التصدير عبر الملف التجميعي وجود واجهة استيراد واحدة ومستقرة.

إعادة تصدير أنواع الجهات الخارجية

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

توثيق النطاق

أضف تعليقات JSDoc إلى الرموز المصدّرة. وبما أن عناصر public-api وحدها مرئية للمستهلكين، فإن توثيقها يوفر للمستخدمين IntelliSense وإرشادات واضحة للاستخدام.

تحقق سريع

ما الذي يحدد ما يمكن للمستهلكين استيراده؟

مراجعة

تُنتقى واجهة البرمجة العامة في public-api.ts، الذي يعيد تصدير المكوّنات والأنواع والرموز؛ بينما يبقى كل ما عدا ذلك خاصًا وقابلًا لإعادة الهيكلة. استخدم نقاط الدخول الثانوية للمكتبات الكبيرة، ووجّه ng-package.json إلى ملف الدخول، وتجنب الاستيرادات العميقة، وتعامل مع النطاق باعتباره عقدًا مستقرًا وموثقًا.

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

هل درس «واجهة API العامة ونقاط الدخول» مجاني؟

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

ماذا ستتعلم في «واجهة API العامة ونقاط الدخول»؟

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

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

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

كم من الوقت يستغرق درس «واجهة API العامة ونقاط الدخول»؟

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

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

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

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

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