Fastfile: الجوهر والبنية وإعداد الأتمتة في تطوير التطبيقات المحمولة

ما هو Fastfile ولماذا تحتاجه

Fastfile هو ملف التكوين الرئيسي لـ Fastlane، مكتوب بلغة Ruby ويوضع في دليل fastlane في جذر المشروع. يحدد جميع سيناريوهات الأتمتة (lanes) لبناء واختبار وتوقيع الكود وتسليم التطبيق. يحل Fastfile محل عشرات نصوص bash وملفات Makefile والتعليمات اليدوية بواصف تصريحي واحد للخط الأنابيب CI/CD.

تنشأ الحاجة إلى Fastfile عندما يتطلب المشروع عمليات بناء قابلة للتكرار على أجهزة مطورين وخوادم CI/CD مختلفة. بدلاً من أن يقوم كل مطور بإعداد البيئة يدويًا، يثبت Fastfile جميع الخطوات في كود يمكن إصداره في Git ومراجعته وإعادة استخدامه بين المشاريع. يضمن Fastfile واحد أن البناء على جهاز المطور مطابق للبناء على خادم CI/CD.

يدعم Fastfile المنصات من خلال توجيه default_platform. في Fastfile واحد يمكن وصف سيناريوهات iOS و Android و macOS، وتجميعها في كتل platform :ios و platform :android. هذا مفيد بشكل خاص للمشاريع عبر المنصات حيث تشترك بنيات iOS و Android في منطق نشر مشترك ولكنها تستخدم أدوات بناء مختلفة.

بنية Fastfile: lanes و actions والمعلمات

يتكون Fastfile من ثلاثة عناصر رئيسية: إعلان المنصة (default_platform)، تعريف lanes، وتكوين الوظائف المساعدة. يبدأ كل lane بالكلمة الأساسية lane، يليها اسم السيناريو (رمز Ruby)، والنص مع سلسلة من الإجراءات وكتل معالجة الأخطاء: error أو success أو ensure.

Actions في Fastfile هي استدعاءات لوظائف Fastlane المدمجة مع معلمات على شكل Hash. على سبيل المثال، gym(scheme: 'App', export_method: 'app-store') تشغل بناء تطبيق iOS بالمعلمات المحددة. ترجع كل action نتيجة يمكن تخزينها في متغير واستخدامها في actions لاحقة — وهذا يتيح منطقًا شرطيًا داخل lane.

يدعم Fastfile متغيرات البيئة من خلال آلية ENV القياسية في Ruby. لا ينبغي تخزين البيانات الحساسة (كلمات المرور، الرموز، المفاتيح) في Fastfile — استخدم متغيرات بيئة نظام CI/CD أو ملف .env مضاف إلى .gitignore. يقوم Fastlane تلقائيًا بتحميل ملفات .env من دليل fastlane عند بدء التشغيل.

Appfile و Matchfile

إلى جانب Fastfile، توجد ملفات تكوين إضافية في دليل fastlane. يحتوي Appfile على معرفات التطبيق (app_identifier) ومعرف Apple ID ومعرف Team ID — يتم إدراج هذه البيانات تلقائيًا في جميع actions، مما يلغي التكرار في كل lane. يخزن Matchfile إعدادات match: عنوان مستودع Git ونوع الملفات التعريفية ومفتاح التشفير.

يساعد تقسيم التكوين على عدة ملفات في تبسيط صيانة المشاريع ذات البيئات المختلفة. على سبيل المثال، لبيئتي staging و production، يمكنك إنشاء فروع منفصلة في مستودع Matchfile أو تجاوز المعلمات من خلال متغيرات البيئة في نظام CI/CD.

# الهيكل الأساسي لـ Fastfile
default_platform(:ios)

lane :build_and_test do
  cocoapods
  scan(scheme: 'App', devices: ['iPhone 15'])
  gym(scheme: 'App')
end

lane :deploy do
  match(type: 'appstore')
  build_and_test
  pilot(skip_waiting_for_build_processing: true)
end

صياغة Fastfile: كتابة lanes

تستند صياغة Fastfile إلى Ruby DSL (لغة خاصة بالمجال)، المصممة خصيصًا لسهولة قراءة سيناريوهات الأتمتة. يُعلن lane من خلال بناء lane :name do ... end، حيث name هو رمز Ruby يصبح الأمر fastlane name للتشغيل من الطرفية أو نظام CI/CD.

داخل lane يمكن استخدام العوامل الشرطية في Ruby: if, unless, case لتفرع المنطق. كما تتوفر حلقات each و while لمعالجة مصفوفات القيم. يوفر Fastlane طرقًا خاصة before_all و after_all وكتل error لمعالجة أحداث دورة حياة lane.

معلمات lane تُمرر من خلال هاش options. عند تشغيل fastlane build --option_name value، تدخل القيمة إلى options[:option_name] داخل lane. يمكن تعيين قيم افتراضية من خلال optional: true والتحقق من النوع للتحكم في أنواع المعلمات التي يتم تمريرها.

# Lane مع معلمات ومنطق شرطي
lane :build do |options|
  scheme = options[:scheme] || 'App'
  export_method = options[:export_method] || 'development'

  match(type: export_method)

  if export_method == 'appstore'
    gym(scheme: scheme, export_method: 'app-store')
    pilot(skip_waiting_for_build_processing: true)
  else
    gym(scheme: scheme, export_method: export_method)
  end
end

مثال Fastfile لتسليم iOS

يتضمن Fastfile كامل لمشروع iOS lanes لتثبيت التبعيات والاختبار والبناء والنشر إلى TestFlight و App Store. لنلق نظرة على مثال يغطي عملية CI/CD نموذجية من الالتزام إلى النشر على TestFlight للاختبار الداخلي.

# Fastfile لتسليم iOS CI/CD
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  setup_travis if ENV['TRAVIS']
end

lane :tests do
  scan(
    scheme: 'App',
    devices: ['iPhone 15', 'iPad Pro 12.9'],
    output_directory: './test_reports'
  )
end

lane :build_appstore do
  match(type: 'appstore', readonly: true)
  gym(
    scheme: 'App',
    export_method: 'app-store',
    include_bitcode: true
  )
end

lane :deploy_testflight do
  build_appstore
  pilot(
    skip_waiting_for_build_processing: true,
    distribute_external: false
  )
  slack(
    message: 'تم رفع البناء إلى TestFlight للاختبار الداخلي'
  )
end

في هذا المثال، يتم تنفيذ كتلة before_all قبل كل lane وتقوم بتثبيت التبعيات. يقوم lane tests بتشغيل اختبارات الواجهة واختبارات الوحدة على جهازين. يقوم lane build_appstore بتوقيع الكود عبر match وبناء IPA مع bitcode. يجمع lane deploy_testflight جميع الخطوات للتسليم الكامل.

النشر بأهداف متعددة

تتطلب المشاريع ذات الأهداف المتعددة (التطبيق الرئيسي، watchOS، widget، Notification Service Extension) lanes منفصلة لكل هدف. في Fastfile يمكن إنشاء lane عالمي :deploy_target يقبل اسم المخطط ومسار البناء كمعلمات. هذا يتيح تشغيل النشر لجميع الإضافات عبر fastlane deploy_target scheme:Widget.

لتنظيم أهداف متعددة، استخدم مصفوفة من المخططات وحلقة each داخل lane. يدعم Fastlane البناء المتوازي لمخططات متعددة من خلال العلم parallel: true، مما يقلل الوقت الإجمالي للخط الأنابيب CI/CD للتطبيقات ذات الإضافات.

مثال Fastfile لبناء Android

يستخدم Fastfile لمشاريع Android إجراء gradle لتشغيل مهام Gradle وإجراء supply للنشر على Google Play. على عكس iOS، لا يتطلب Android match، لكنه يستخدم Keystore للتوقيع، الذي يُخزن خارج المستودع ويُمرر عبر متغيرات البيئة.

# Fastfile لبناء Android CI/CD
default_platform(:android)

lane :build_release do
  gradle(task: 'clean')
  gradle(task: 'bundleRelease')
  gradle(task: 'assembleRelease')
end

lane :deploy_internal do
  build_release
  supply(
    track: 'internal',
    aab: 'app/build/outputs/bundle/release/app-release.aab',
    release_status: 'completed'
  )
end

لتوقيع تطبيق Android، قم بتكوين signingConfigs في build.gradle ومرر معلمات Keystore عبر متغيرات البيئة: ANDROID_KEYSTORE_PATH و ANDROID_KEYSTORE_PASSWORD و ANDROID_KEY_ALIAS و ANDROID_KEY_PASSWORD. يستخدم Fastlane تلقائيًا apksigner النظام لتوقيع AAB أو APK المبني.

توقيع Android في Fastfile

لتكوين توقيع Android في Fastfile، استخدم إجراء sign_android أو اعتمد على signingConfigs في build.gradle. يتكامل Fastlane مع apksigner عبر Gradle — تمرير العلم SIGNING_CONFIG في مهمة gradle ينشط التوقيع بمعلمات من متغيرات البيئة. هذا يسمح بتوقيع ملفات AAB قبل الرفع إلى Google Play Console.

لتخزين Keystore بشكل آمن في CI/CD، استخدم ترميز Base64 ومتغيرات البيئة. يدعم Fastlane إجراء setup_keystore، الذي يفك ترميز Keystore من متغير ويحفظه في ملف مؤقت خلال مرحلة before_all. بعد اكتمال lane، يُحذف الملف المؤقت تلقائيًا لمنع تسرب الشهادات.

استخدام private lanes والمجموعات

Private lanes (السيناريوهات الخاصة) هي lanes لا يمكن استدعاؤها مباشرة من سطر الأوامر، ولكنها متاحة للاستدعاء من lanes أخرى داخل Fastfile. يُعلن private lane من خلال بناء private_lane :name do ... end ويُستخدم لتغليف الخطوات المتكررة التي ليس لها معنى كسيناريوهات مستقلة.

تعتبر private lanes مثالية لتجميع المنطق المتكرر: تثبيت التبعيات، إعداد البيئة، إرسال الإشعارات. على سبيل المثال، يمكن إنشاء private lane :setup_signing يُستدعى من عدة lanes نشر، ولكن لا ينبغي أن يكون متاحًا للتشغيل المباشر من قبل المطور لتجنب الأخطاء.

# Private lane والتجميع
default_platform(:ios)

private_lane :setup_signing do |options|
  match(
    type: options[:type],
    readonly: true,
    verbose: false
  )
end

lane :beta do
  setup_signing(type: 'adhoc')
  gym(export_method: 'ad-hoc')
  pilot(distribute_external: true)
end

lane :release do
  setup_signing(type: 'appstore')
  gym(export_method: 'app-store')
  deliver(
    force: true,
    submit_for_review: true
  )
end

تجميع lanes من خلال كتل platform يسمح بفصل سيناريوهات iOS و Android في Fastfile واحد. بناء platform :ios do ... end و platform :android do ... end يعزل lanes للمنصة المقابلة، بينما يمكن وضع private lanes المشتركة خارج كتل المنصة لإعادة الاستخدام.

تمرير المعلمات إلى lanes

تتيح آلية المعلمات في Fastfile جعل lanes مرنة وقابلة لإعادة الاستخدام. تُمرر المعلمات أثناء التشغيل عبر سطر الأوامر: fastlane build scheme:App export_method:appstore. داخل lane، تكون القيم متاحة من خلال هاش options، الذي يُمرر إلى كتلة lane كوسيطة.

يدعم Fastlane معلمات بنوع محدد مع التحقق عبر OptionalHash. يمكن تحديد نوع القيمة (String, Boolean, Integer)، وقيمة افتراضية، ووصف للتوليد التلقائي للتوثيق. تتوفر متغيرات البيئة أيضًا كطريقة بديلة لتمرير المعلمات، وهو أمر مناسب لأنظمة CI/CD.

# معلمات مع التحقق من الأنواع
lane :build do |options|
  gym(
    scheme: options[:scheme],
    export_method: options[:export_method] || 'development',
    include_bitcode: options[:include_bitcode] || false,
    output_name: options[:output_name]
  )
  slack(message: "بناء #{options[:scheme]} اكتمل")
end

# التشغيل: fastlane build scheme:MyApp export_method:appstore

يُوصى باستخدام قيم افتراضية لجميع المعلمات الاختيارية، بحيث يمكن تشغيل lane دون تحديد كل وسيطة بشكل صريح. للمعلمات الإلزامية، تحقق من وجودها في بداية lane وأوقف التنفيذ برسالة خطأ واضحة باستخدام UI.user_error!.