Fastfile: същност, структура и настройка на автоматизация в мобилната разработка

Какво е Fastfile и защо е необходим

Fastfile е основният конфигурационен файл на Fastlane, написан на Ruby и разположен в директорията fastlane в корена на проекта. Той определя всички сценарии за автоматизация (lanes) за компилиране, тестване, подписване на код и доставка на приложението. Fastfile замества десетки bash скриптове, Makefile и ръчни инструкции с единно декларативно описание на CI/CD pipeline.

Необходимостта от 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 :име do ... end, където името е Ruby символ, който става командата fastlane име за стартиране от терминал или CI/CD система.

Вътре в lane могат да се използват условни оператори на Ruby: if, unless, case за разклоняване на логиката. Също така са достъпни цикли each и while за обработка на масиви от стойности. Fastlane предоставя специални методи before_all, after_all и error блокове за обработка на събития от жизнения цикъл на lane.

Параметрите на lane се предават чрез options hash. При стартиране 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 за 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 стартира UI и Unit тестове на две устройства. 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 pipeline за приложения с разширения.

Пример за Fastfile за Android компилиране

Fastfile за Android проект използва gradle action за стартиране на Gradle задачи и supply action за публикуване в 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 използвайте action sign_android или разчитайте на signingConfigs в build.gradle. Fastlane се интегрира с apksigner чрез Gradle – предаването на флага SIGNING_CONFIG на gradle задача активира подписване с параметри от променливи на средата. Това позволява подписване на 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 :име 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 hash, който се предава на 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!.