توليد الشيفرة باستخدام build_runner

بعض الأكواد عبارة عن تعليمات تمهيدية متكررة، مثل تحليل JSON. تكتب Code generation هذه الأكواد نيابةً عنكم انطلاقًا من التعليقات التوضيحية، فتظلون دقيقين وسريعين. ⚙️

إن build_runner أداة Dart التي تشغّل مولدات الكود على مشروعكم. فهي تقرأ ملفات المصدر، وتعثر على التعليقات التوضيحية، وتُصدر ملفات جديدة.

تضيفون build_runner ضمن dev_dependencies في pubspec.yaml، لأنه يعمل وقت البناء ولا يُضمَّن مطلقًا مع تطبيقكم.

تكتب المولِّدات في ملف مجاور. وتربطون به باستخدام توجيه part، وينتهي اسمه اصطلاحًا باللاحقة ‎.g.dart.

شغّلوا التوليد لمرة واحدة باستخدام الأمر build. يفحص هذا الأمر شيفرتكم وينشئ كل ملف ‎.g.dart أو يحدّثه.

أثناء التطوير، يعيد وضع watch التوليد تلقائيًا كلما حفظتم الملف. ويحافظ على مزامنة الملفات المُولَّدة دون الحاجة إلى إعادة التشغيل يدويًا.

إذا تعارضت المخرجات مع ملفات قديمة، أضيفوا --delete-conflicting-outputs. فهذا يحذف الملفات المُولَّدة القديمة حتى ينجح البناء الجديد.

لا تعمل المولِّدات إلا على التصريحات التي تضعون لها annotate. إذ تخبر التعليقة التوضيحية أداة البناء بالفئة التي يجب معالجتها والشيفرة التي ينبغي إنتاجها.

تعاملوا مع كل ملف ‎.g.dart على أنه read-only. سيستبدل البناء التالي تعديلاتكم، لذا عدّلوا المصدر والتعليقات التوضيحية بدلًا من ذلك.

تختار الفرق إما تضمين الملفات المُولَّدة في المستودع، أو إضافتها إلى .gitignore وإعادة بنائها في CI. في كلتا الحالتين، اختاروا سياسة واحدة والتزموا بها.

تتصل حزم كثيرة بـ build_runner، مثل json_serializable وfreezed. وهي تشترك في مسار builder واحد، لذلك يشغّلها أمر واحد جميعًا.

ما الأمر الذي يعيد توليد الشيفرة عند كل حفظ للملف؟

يحوّل build_runner التعليقات التوضيحية إلى ملفات ‎.g.dart مُولَّدة. أضيفوه إلى dev_dependencies، وشغّلوا build أو watch، ولا تعدّلوا المخرجات مطلقًا. 🎉