ng best practices
1.0.0
يهدف هذا المشروع إلى أن يكون مثال الدعم على برنامج تعليمي يسير لك من خلال أفضل ممارسات التطوير الأمامي (الويب/الهاتف المحمول) مع مثال ملموس يعتمد على مشروع زاوي.
لرؤية البرنامج التعليمي يأتي في أقرب وقت ممكن يمكنك التصويت هنا.
هذا المشروع هو نتيجة لتجربتي في مساعدة الشركات الناشئة والمزيد من الصناعات التقليدية (في التمويل والهيئة المكانية) التي تحدد وتطوير مشاريعها الأمامية (الويب والموبول).
لقد لاحظت أنه في كل مرة ، فإن أحد أصعب الأجزاء عند إطلاق منتج هو تحديد أفضل الممارسات وإيجاد أفضل الأدوات لوضع سير عمل التطوير.
لذلك قررت إنشاء هذا المشروع ، لكي أكون تركيزًا لأفضل الممارسات جاهزة للاستخدام خارج الصندوق وقد ينقذ ذلك المطورين وأيام المهندسين المعماريين التقنيين/المهندسين الفنيين وحتى شهور من العمل الشاق للعثور على أفضل سير عمل لمشاريعهم.
هذا المشروع/البرنامج التعليمي التركيز الرئيسي هو أفضل الممارسات التنمية. لذلك ، للبداية ، لن يتضمن أي مادة تتعلق بالتكامل المستمر أو نشر التطبيق.
إشعار 1: العديد من أفضل الممارسات الموجودة في هذا المشروع ، كما ذكرنا من قبل ، عام للتطوير الأمامي وحتى للتطوير بشكل عام (ليس فقط الواجهة الأمامية) ، لذلك حتى لو كنت لا تستخدم Angular في مشروعك ، يمكنك المشي من خلال الحصول على بعض الأفكار المثيرة للاهتمام.
إشعار 2: يمكنك رؤية محتوى مشروع مختلف يرتكب فكرة عن تطور المشروع وخطوات إضافة/تضمين أداة أو مكتبة أو نمط معين إلى المشروع.
تم إنشاء هذا المشروع مع الإصدار 7.3.1 Angular CLI.
لهذا المشروع أنا أستخدم الغزل بشكل رئيسي. ولكن يمكنك تشغيل نفس البرامج النصية/الأوامر باستخدام NPM.
على سبيل المثال لبدء المشروع باستخدام yarn ، يمكنك تشغيل yarn start . للقيام بنفس الشيء باستخدام npm يمكنك تشغيل npm run start .
لتتمكن من إطلاق هذا المشروع ، تحتاج إلى تثبيت:
npm لتشغيل نصوص مختلفة. (خياري)قبل أن تتمكن من بدء المشروع ، يجب عليك تثبيت التبعيات/المكتبات المختلفة. للقيام بذلك:
# if npm
npm install
# if yarn
yarn
فيما يلي قائمة بالأدوات الاختيارية التي قد تحتاجها بشكل عام لتطوير مشاريعك:
الفرع الرئيسي حيث يمكنك العثور على أحدث رمز العمل والاختبار هو السيد.
يمكنك متابعة الالتزامات اليومية والتطوير على فرع التطوير.
سيأتي نظام وضع العلامات على ترقيات وإصدارات مختلفة للمشروع.
تشغيل yarn start لخادم dev. انتقل إلى http://localhost:4200/ . سيتم إعادة تحميل التطبيق تلقائيًا إذا قمت بتغيير أي من الملفات المصدر.
تشغيل ng generate component component-name لإنشاء مكون جديد. يمكنك أيضًا استخدام ng generate directive|pipe|service|class|guard|interface|enum|module .
تشغيل yarn build لبناء المشروع. سيتم تخزين القطع الأثرية البناء في dist/ Directory. استخدم العلم --prod لبناء الإنتاج.
في الواقع ، يستخدم المشروع الافتراضي الذي تم إنشاؤه عن الزاوي أداة KARMA لاختبار الوحدة. المشكلة في Karma (يمكن أن تكون ميزة في بعض الحالات) ، هي أنها تحتاج إلى تشغيل متصفح لإجراء اختبار لا ضروري في كثير من الحالات ، وفي الوقت نفسه يمتد وقت تنفيذ الاختبار. بالإضافة إلى ذلك ، قد يكون لديك تكامل مستمر متكامل لك عملية التطوير/التسليم التي تعمل على بيئة يمكن أن يكون لديك متصفح.
هناك بديل مثير للاهتمام Karma وهو Jest. يجعلها أسرع وأسهل في كتابة الاختبارات. لا حاجة إلى متصفح. لأنه يأتي مع القدرات المدمجة والتأكيد. بالإضافة إلى ذلك ، يدير Jest اختباراتك بشكل متزامن بالتوازي ، مما يوفر اختبارًا أكثر سلاسة وأسرع.
Jest-Preset-angular: يستخدم لجعل التكوين Jest أسهل. الإصدار الفعلي المستخدم هو 6.0.2 ، لذا فإن الوثائق والتكوين ستكون مختلفة بالنسبة للإصدارات المستقبلية لهذه المكتبة.
قم بتشغيل yarn test:all لتنفيذ اختبارات الوحدة عبر Jest في المشروع بأكمله.
إذا كنت ترغب في تشغيل اختبارات الوحدة في مشروع معين مثل اختبار connection Project Run yarn test:connection . لا تنس إضافة البرنامج النصي المطلوب إلى ملف package.json في Addiion إلى ملف تكوين Jest Matching ليتمكن من إطلاق الاختبار على مكتبة جديدة. يمكنك أخذ مثال على كيفية القيام به لمكتبة connection .
يمكنك أيضًا تشغيل اختباراتك ومشاهدة التغييرات من خلال التشغيل yarn test:all:watch .
VS Code و Jest Debug: إذا كنت تستخدم VS Code ، فيمكنك تصحيح اختبارات الوحدة المستندة إلى Jest عن طريق إضافة ملف launch.json ضمن مجلد .vscode الخاص بك (يمكنك العثور على ملف مثال في الريبو الفعلي). سوف يستخدم مصحح الأخطاء مصحح أخطاء العقدة المدمجة. يمكن أن تكون الوثائق الأكثر اكتمالا مولعة هنا.
قم بتشغيل yarn e2e لتنفيذ الاختبارات الشاملة عبر المنقلة.
إذا أردنا استيراد مكون من مكتبة connection فيمكننا استخدام شرح @connection .
مثال: import { ConnectionModule } from '@connection' ؛
هذا ممكن بفضل إضافة سمة paths إلى ملف tsconfig.json .
"compilerOptions" : {
...,
"paths" : {
"@connection" : [
" projects/connection/src/public_api "
],
...
},
...
} إذا أردنا الحصول على مزيد من التحديد حول المسار (على سبيل المثال في حالة التبعية الدائرية) ، يمكننا إضافة مسار آخر إلى ملف tsconfig.json مثل المتابعة:
"compilerOptions" : {
...,
"paths" : {
"@connection" : [
" projects/connection/src/public_api "
],
"@connection/*" : [
" projects/connection/src/* "
]
...
},
...
}سوف يسمح باستيراد المكونات أو غيرها من الوظائف التي تم تصديرها الزاوي مثل المثال التالي:
مثال: import { ConnectionComponent } from '@connection/lib/modules/main/pages'; ؛
للتأكد من أن المطورين يتبعون خطوط عمل دقيقة أثناء الارتباط ودفع الرمز ، بحيث لا يتعين عليك القيام بالإقصارات وتشغيل البرامج النصية يدويًا ، فإن الأدوات التالية مفيدة للغاية:
في package.json تضيف:
" scripts " {
"commit" : " git-cz " ,
...
} لذلك عندما تقوم بتشغيل yarn commit يتم استخدام cz-cli . لذلك لا مزيد من git commit المباشر.
cz-cli . في package.json تضيف:
"config" : {
"commitizen" : {
"path" : " node_modules/cz-customizable "
},
"cz-customizable" : {
"config" : " path/to/custom/cz-config.js "
}
},
... إذا لم تعطي أي ملف مخصص في التكوين ( config.cz-customizable.config ) ، سيتم استخدام ملف .cz-config.js الموجود في جذر المشروع.
ملاحظة: لكي تكون قادرًا على استخدام VS Code لتحرير تعليقات GIT أو مهام معالجة الملفات الأخرى بدلاً من vim الافتراضي ، يمكنك تشغيل git config --global core.editor "code --wait" في Condicting بأن الكود VS متوفر من خط Commande (يمكنك التحقق من ذلك عن طريق تشغيل code --help ).
مزيد من المعلومات هنا.
أضف تكوين husky في جذر ملف package.json :
"husky" : {
"hooks" : {
"pre-commit" : " yarn lintstaged " ,
"prepush" : " yarn prod "
}
} إذا كنت ترغب في تخطي Hools ، فما عليك سوى إضافة العلم --no-verify إلى أمر GIT الخاص بك. مثال: git push --no-verify
لذا ، إلى تكوين husky Hooks المحدد بالفعل ، يمكنك إضافة خطاف commit-msg :
"husky" : {
"hooks" : {
...,
"commit-msg" : " commitlint -E HUSKY_GIT_PARAMS "
}
} يتيح لك commit-msg Hook ارتكاب الوبر قبل إنشائها.
يمكنك إضافة ملف commitlint.config.js في جذر المشروع ، لتحديد قواعد/اتفاقيات linting.
مثال على commitlint.config.js :
module . exports = {
// we use the default @commitlint/config-conventional rules.
// you have to install @commitlint/config-conventional library to be able to use it.
extends : [ '@commitlint/config-conventional' ] ,
// Any rules defined here will override rules from @commitlint/config-conventional
// => custom rules
rules : {
'header-max-length' : [ 2 , 'always' , 100 ] ,
'subject-case' : [
2 ,
'never' ,
[ 'sentence-case' , 'start-case' , 'pascal-case' , 'upper-case' ]
] ,
...
}
} ; ملاحظة: إذا كنت ترغب في إعادة محاولة التزام بحيث لا تضطر إلى إعادة إدخال نفس المعلومات مرة أخرى ، فما عليك سوى تشغيل yarn commit:retry .
تم استخدام Routermodule الزاوي. وثائق Angular كاملة للغاية وأنصحك بإلقاء نظرة عليها.
في هذا المشروع ، لقد اخترت أنه بالنسبة app (تطبيقات) التطبيق (المستقل) ، أستخدم التوجيه/التحميل المباشر. من ناحية أخرى ، بالنسبة للتطبيق الرئيسي (تطبيق الجذر) ، يتم تحميل الوحدة النمطية كسول ويؤثر على الطريقة التي يعمل بها التوجيه.
لمعرفة كيف ، يمكن معالجة تحميل LZAY إلقاء نظرة على دليل src/app/lazy حيث يتم تعريف الوحدات المحملة كسول. ثم يتم تحميل هذه الوحدات "حقًا" كسولًا داخل ملف src/app/app-routing.module.ts . لكل وحدة محملة كسول ، يتم تعريف المسار. يجب أن يسبق هذا المسار جميع المسارات المحددة في الوحدة الأصلية.
exemple: لنفترض أنه في الوحدة النمطية الخاصة بك ، يمكنك الوصول إلى محتوى page-one عبر عنوان URL localhost:4200/page-one عند تحميله (كما هو الحال في مشروع التطبيق/المستقل). في الوقت نفسه ، فإن المسار الذي حددته لتحميل الكسول نفس الوحدة هو my-lazy-loaded-path . لذلك للوصول إلى نفس المحتوى/الصفحة ، يجب عليك استخدام عنوان URL localhost:4200/my-lazy-loaded-path/page-one بدلاً من ذلك.
وهنا لجعل الوحدة النمطية تعمل أثناء تحميلها كسول محملة أو محملة مباشرة ، يتم استخدام مجموعة من طريقة forRoot على الوحدة النمطية المحملة ومتغيرات البيئة.
عندما يتعلق الأمر بمعالجة الأشكال ، يكون لديك الاختيار بين الأشكال التفاعلية والأشكال القائمة على القالب.
في الوثائق الزاوية الرسمية يمكنك العثور عليها:
الأشكال التفاعلية أكثر قوة: إنها أكثر قابلية للتطوير ، وقابلة لإعادة الاستخدام ، ويمكن اختبارها. إذا كانت النماذج جزءًا أساسيًا من التطبيق الخاص بك ، أو كنت تستخدم بالفعل أنماط تفاعلية لبناء التطبيق الخاص بك ، فاستخدم النماذج التفاعلية.
تعد النماذج التي تعتمد على القالب مفيدة لإضافة نموذج بسيط إلى تطبيق ، مثل نموذج تسجيل قائمة البريد الإلكتروني. من السهل إضافتها إلى التطبيق ، لكنها لا تتوسع وكذلك النماذج التفاعلية. إذا كان لديك متطلبات النماذج الأساسية والمنطق التي يمكن إدارتها فقط في القالب ، فاستخدم النماذج القائمة على القالب.
يمكنك العثور على جدول من الاختلافات الرئيسية هنا.
بالنسبة لهذا المشروع ، اخترت استخدام النماذج التفاعلية لجميع المزايا التي يأتي مع وجود نموذج بيانات مختصر أو الاستفادة من التزامن بين القالب الخاص بك (View/HTML) و Controller (فئة المكونات/النموذج). علاوة على ذلك ، بشكل عام ، في المشاريع الكبيرة ، قد يكون لديك أشكال معقدة reactive forms تجعل المهمة أسهل لك.
عند تشغيل مشروعك ، يمكنك وضعه أولاً على مكتبة التصميم الموجودة بالفعل. يساعدك ذلك في توفير الوقت عند تصميم التطبيق الخاص بك.
فيما يلي بعض الأمثلة على المكتبات التي يمكنك استخدامها:
في الواقع ، بالنسبة لهذا المشروع ، فإن bootstrap تم استخدامه (وليس ng-boostrap ).
تم تصميم معظم المكتبات مثل React و Angular ، وما إلى ذلك بطريقة للمكونات لإدارة حالتها داخليًا دون أي حاجة إلى مكتبة أو أداة خارجية. إنه جيد للتطبيقات التي تحتوي على عدد قليل من المكونات ، ولكن مع نمو التطبيق أكبر ، تصبح الدول الإدارة المشتركة عبر المكونات مهمة روتينية.
في التطبيق الذي تتم مشاركة البيانات بين المكونات ، قد يكون من المربك معرفة مكان العيش في الواقع. من الناحية المثالية ، يجب أن تعيش البيانات الموجودة في المكون في مكون واحد فقط. لذا فإن مشاركة البيانات بين مكونات الأخوة تصبح أمرًا صعبًا (المصدر).
الطريقة التي تعمل بها مكتبة إدارة الدولة بسيطة. يوجد متجر مركزي يحمل الحالة بأكملها للتطبيق. يمكن لكل مكون الوصول إلى الحالة المخزنة دون الحاجة إلى إرسال الدعائم من مكون إلى آخر.
على سبيل المثال ، بالنسبة إلى React واحدة من أكثر مكتبات إدارة الدولة المستخدمة هو Redux. واستخدام حزمة React-Redux يجعل الأمر أسهل. بالتأكيد ، لديك مكتبات أخرى لإدارة الدولة react مثل تدفق Facebook. لذا ، اختر ما يناسبك أكثر ما يعلق على أن redux يستخدم هذا flux لأنه لا يتمركز على react ويمكن استخدامه مع أي مكتبة عرض أخرى.
بالنسبة إلى angular لديك العديد من الخيارات لإدارة الدولة مثل:
بالنسبة إلى Angular ، بعد دراسة الخيارات المختلفة ، أجد أن ngxs هو الخيار الأفضل. إنه مكتوب لـ Angular في المقام الأول ، بحيث يتم تنفيذه بعد نمط رمز الزاوي ويأخذ ويحصل على Dependency Injection المقدمة بواسطة Angular . بالإضافة إلى ذلك ، فهو أقل مطوّلة ثم مكتبات أخرى. لهذه الأسباب ، اتخذنا خيار استخدامه في العديد من الشركات التي عملت معها. يمكنك العثور هنا على شرح كامل لسبب استخدام ngxs .
مكونات ngxs المستخدمة لهذا الريبو:
نمط الواجهة هو نمط تصميم البرامج شائع الاستخدام في البرمجة الموجهة للكائنات. على غرار واجهة في الهندسة المعمارية ، فإن الواجهة هي كائن بمثابة واجهة أمامية لا تقلق رمزًا أساسيًا أو هيكليًا أكثر تعقيدًا. يمكن الواجهة:
في حين أن هذا يبدو وكأنه تغيير تافعي إلى حد ما (وطبقة إضافية) ، فإن الواجهة لها تأثير إيجابي كبير لإنتاجية المطورين وتعطي تعقيدًا أقل بكثير في طبقات العرض (المصدر).
ميزة أخرى هي أنها تجعل وحدات التحكم الخاصة بك (المكونات الزاوية على سبيل المثال) ، المستقلة من مكتبة إدارة الولاية التي اخترتها لاستخدامها.
للتدويل لديك خياران:
1 - استخدم نظام i18n Angular's
2 - استخدم مكتبة NGX -Translate.
لن أخوض في التفاصيل ، لكن اختيار هذا المشروع والعديد من الإنتاج الآخر مثل المشاريع هو استخدام ngx-translate . الأسباب الرئيسية هي أنه ، لنفس النتيجة ، من الأسهل استخدام وتطوير مع Angular i18n يجبرك على بناء التطبيق لكل لغة ويعيد تحميل التطبيق على تغيير اللغة.
للحصول على مزيد من المساعدة على CLI الزاوي ، استخدم ng help أو انتقل إلى راجع الزاوي cli readme.
إذا كنت تستخدم VS Code ، فقد تجد الإضافات التالية مفيدة للغاية:
حقوق الطبع والنشر بواسطة @Haythem-Ouederni. يتم إصدار جميع مصادر المشروع بموجب ترخيص Apache.
