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)، بدنه با دنباله actions و بلوک‌های مدیریت خطا 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 را ذخیره می‌کند: URL مخزن 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 (Domain Specific Language) است که به طور ویژه برای خوانایی سناریوهای خودکارسازی طراحی شده است. 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 از طریق hash options منتقل می‌شوند. هنگام اجرای fastlane build --option_name value مقدار وارد options[:option_name] در داخل lane می‌شود. می‌توان مقادیر پیش‌فرض را از طریق optional: true و اعتبارسنجی type برای کنترل انواع پارامترهای منتقل شده تنظیم کرد.

# 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 را از commit تا انتشار در TestFlight برای آزمایش داخلی پوشش می‌دهد.

# Fastfile برای تحویل CI/CD iOS
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 آزمایش‌های UI و واحد را روی دو دستگاه اجرا می‌کند. Lane build_appstore کد را از طریق match امضا می‌کند و IPA را با bitcode می‌سازد. Lane deploy_testflight تمام مراحل را برای تحویل کامل ترکیب می‌کند.

استقرار با چندین target

پروژه‌های با چندین target (برنامه اصلی، watchOS، ویجت، Notification Service Extension) برای هر target به lanes جداگانه نیاز دارند. در Fastfile می‌توان یک lane جهانی :deploy_target ایجاد کرد که نام طرح و مسیر ساخت را به عنوان پارامتر دریافت می‌کند. این امکان اجرای استقرار برای تمام extensions را از طریق fastlane deploy_target scheme:Widget فراهم می‌کند.

برای سازماندهی چندین target از آرایه طرح‌ها و حلقه each در داخل lane استفاده کنید. Fastlane از ساخت موازی چندین طرح از طریق پرچم parallel: true پشتیبانی می‌کند که زمان کل خط لوله CI/CD را برای برنامه‌های با extensions کاهش می‌دهد.

مثال Fastfile برای ساخت Android

Fastfile برای پروژه Android از gradle action برای اجرای وظایف Gradle و supply action برای انتشار در Google Play استفاده می‌کند. برخلاف iOS، Android به match نیاز ندارد، اما از Keystore برای امضا استفاده می‌کند که خارج از مخزن ذخیره شده و از طریق متغیرهای محیطی منتقل می‌شود.

# Fastfile برای ساخت CI/CD Android
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 از action sign_android استفاده کنید یا به signingConfigs در build.gradle اعتماد کنید. Fastlane از طریق Gradle با apksigner ادغام می‌شود — انتقال پرچم SIGNING_CONFIG در gradle task امضا را با پارامترهای متغیرهای محیطی فعال می‌کند. این امکان امضای فایل‌های AAB را قبل از بارگذاری در Google Play Console فراهم می‌کند.

برای ذخیره امن Keystore در CI/CD از کدگذاری Base64 و متغیرهای محیطی استفاده کنید. Fastlane از action 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 ایجاد کرد که از چندین lane استقرار فراخوانی می‌شود، اما برای جلوگیری از خطاها نباید برای اجرای مستقیم توسط توسعه‌دهنده در دسترس باشد.

# 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 مشترک را می‌توان برای استفاده مجدد خارج از بلوک‌های platform قرار داد.

انتقال پارامترها به lanes

مکانیزم پارامترها در Fastfile به lanes امکان انعطاف‌پذیری و قابلیت استفاده مجدد می‌دهد. پارامترها هنگام اجرا از طریق خط فرمان منتقل می‌شوند: fastlane build scheme:App export_method:appstore. در داخل lane مقادیر از طریق hash 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! متوقف کنید.