Lane — какво е, създаване и използване във Fastlane

Какво е Lane във Fastlane

Lane е основният градивен елемент на Fastlane, който дефинира именован сценарий за автоматизация. Всеки lane описва последователност от действия (actions), които се изпълняват за постигане на конкретна цел: да се изгради приложението, да се стартират тестове, да се качи сборката в магазина или да се конфигурира средата. Lane се декларира във Fastfile и се стартира с командата fastlane [име_lane] от коренната директория на проекта.

Концепцията lane е заимствана от Ruby DSL и осигурява четимост на сценариите. Разработчикът вижда целия CI/CD процес като последователност от извиквания на actions с разбираеми имена и параметри. Lane може да бъде прост (една команда) или сложен (разклонения, цикли, извиквания на други lanes).

Всеки lane след изпълнение връща резултат — обект, съдържащ статуса на изпълнение и данни от actions. Резултатът може да се използва в други lanes или да се предаде на CI/CD системата за вземане на решения. Ако някое action в lane се провали, изпълнението на lane спира и се извиква блокът error.

Синтаксис на lane: деклариране и стартиране

Синтаксисът за деклариране на lane следва прост модел на Ruby DSL: ключова дума lane, име на сценария като Ruby символ (symbol), блок do ... end с тяло на сценария. Името на lane трябва да бъде уникално в рамките на платформата и да се състои от букви, цифри и долни черти.

Стартирането на lane се извършва чрез командния ред: fastlane build (за lane с име :build) или bundle exec fastlane build (ако Fastlane е инсталиран чрез Bundler). За платформени lanes използвайте fastlane ios build или fastlane android build.

# Деклариране на прост lane
lane :test do
  scan(scheme: 'App', devices: ['iPhone 15'])
end

lane :build_and_deploy do
  cocoapods
  test
  gym(scheme: 'App', export_method: 'app-store')
  pilot(skip_waiting_for_build_processing: true)
end

# Стартиране: fastlane build_and_deploy

Lane може да съдържа условна логика на базата на параметри или променливи на средата. Използвайте if/unless за пропускане на стъпки при определени условия. Също така са налични цикли each за обработка на масиви, което е удобно за изграждане на множество targets или схеми на приложението в един lane.

Връщане на стойност от lane

Lane може да връща стойност, която ще бъде достъпна за извикващия код. За връщане се използва обичайният Ruby return или последният израз в блока на lane. Върнатата стойност може да бъде низ, число, hash или резултат от action. Това позволява използването на резултата от един lane в друг lane за вземане на решения.

Например, lane :get_version може да върне текущата версия на приложението от Info.plist, а lane :deploy да я използва за формиране на съобщение в Slack. Върнатите стойности са особено полезни в private lanes, където резултатът е необходим за по-нататъшна обработка в извикващия lane.

Параметри на lanes: предаване и обработка

Параметрите на lane правят сценариите гъвкави и многократно използваеми. Lane приема параметри чрез options hash, който се предава при стартиране от командния ред: fastlane deploy scheme:AppStore version:2.1.0. Вътре в lane параметрите са достъпни като options[:scheme] и options[:version].

За задължителни параметри проверявайте наличието на стойност в началото на lane и извиквайте UI.user_error! с ясно съобщение. За незадължителни параметри задавайте стойности по подразбиране чрез оператора ||. Fastlane също поддържа типизирани параметри чрез метода options с посочване на тип, стойност по подразбиране и описание.

# Lane с обработка на параметри
lane :deploy do |options|
  scheme = options[:scheme]
  version = options[:version] || '1.0.0'
  beta = options[:beta] || false

  UI.user_error!("Не е посочено scheme") unless scheme

  match(type: beta ? 'adhoc' : 'appstore')
  gym(scheme: scheme, export_method: beta ? 'ad-hoc' : 'app-store')

  if beta
    pilot(distribute_external: true)
  else
    deliver(submit_for_review: true)
  end
end

# Стартиране: fastlane deploy scheme:MyApp beta:true version:2.1.0

За работа с променливи на средата вътре в lane използвайте ENV['VARIABLE_NAME']. Fastlane автоматично зарежда .env файлове от директорията fastlane. Това е стандартният начин за предаване на чувствителни данни — API ключове, пароли и токени — в CI/CD среда без съхранението им във Fastfile.

Валидация на параметри

За надеждна работа на lane е необходима валидация на параметрите на входа. Използвайте UI.user_error! с описание на проблема, ако задължителен параметър липсва или има грешен тип. Fastlane предоставя метода options, който позволява задаване на тип (String, Boolean, Integer, Array), стойност по подразбиране и описание за всеки параметър — валидацията се изпълнява автоматично при стартиране на lane.

Допълнително можете да използвате проверки чрез verify блок: verify do |value| value.length > 0 end за низови параметри. При грешен формат Fastlane показва ясно съобщение с очаквания формат и предадената стойност, което улеснява отладката в CI/CD среда.

Комбиниране на lanes: before_all, after_all и error обработка

Fastlane предоставя hooks на жизнения цикъл за изпълнение на код преди и след всеки lane. Блокът before_all се изпълнява преди всеки lane в дадената платформа или глобално. Блокът after_all се изпълнява след успешно завършване на lane. Блокът error се изпълнява при всяка грешка вътре в lane.

Hooks позволяват централизиране на повтаряща се логика: инсталиране на зависимости в before_all, изпращане на уведомления в after_all, почистване на временни файлове и уведомяване за грешки в error блок. Това намалява дублирането на код и прави lanes по-чисти.

# Хукове на жизнения цикъл на lanes
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  ensure_git_status_clean
end

after_all do |lane|
  slack(message: "Lane #{lane} выполнен успешно")
end

error do |lane, exception|
  slack(
    message: "Lane #{lane} упал с ошибкой: #{exception}",
    success: false
  )
end

lane :deploy do
  match(type: 'appstore')
  gym(export_method: 'app-store')
  deliver
end

Блокът error получава два аргумента: името на lane (symbol) и обекта на изключението. Вътре в блока можете да изпратите уведомление в Slack, да запишете лог във файл или да стартирате алтернативен сценарий за възстановяване. Ако error блокът завърши успешно, Fastlane не счита сборката за провалена на ниво CI/CD.

Private lanes и повторна употреба

Private lane е lane, деклариран чрез private_lane вместо lane, който не се показва в списъка на достъпните команди и не може да бъде стартиран директно от терминала. Private lanes са предназначени за капсулиране на повтарящи се стъпки, които се извикват от множество публични lanes.

Private lanes са особено полезни за сложни последователности от действия, които трябва да се изпълняват в строго определен ред. Например, private lane :setup_signing може да се извиква от lanes :build_dev, :build_staging и :build_production с различни параметри, но само по себе си няма смисъл като отделна команда.

# Private lanes за повторна употреба
private_lane :setup_environment do |options|
  cocoapods(try_repo_update_on_error: true)
  match(type: options[:type], readonly: true)
  increment_build_number
end

lane :dev_build do
  setup_environment(type: 'development')
  gym(export_method: 'development')
end

lane :appstore_build do
  setup_environment(type: 'appstore')
  gym(export_method: 'app-store')
  deliver
end

Private lanes могат да извикват други private lanes, образувайки йерархия на абстракциите. Препоръчва се ограничаване на дълбочината на влагане до 2–3 нива за запазване на четимостта на Fastfile. Документирайте всеки private lane с коментар, описващ неговото предназначение и очакваните параметри.

Примери за lanes за iOS и Android

Нека разгледаме практически примери за lanes за iOS и Android проекти. iOS lanes обикновено използват scan за тестове, match за сертификати, gym за изграждане и pilot или deliver за доставка. Android lanes използват gradle за изграждане, supply за публикуване и firebase_test_lab за облачно тестване.

// Lane за пълно CI/CD на iOS приложение
lane :ci_full_ios do
  scan(scheme: 'App', code_coverage: true)
  gym(scheme: 'App', export_method: 'app-store')
  pilot(distribute_external: true)
  slack(message: 'iOS CI/CD завърши успешно')
end

/* Lane за пълно CI/CD на Android приложение */
lane :ci_full_android do
  gradle(task: 'testReleaseUnitTest')
  gradle(task: 'bundleRelease')
  supply(track: 'internal')
end

Комбинирайки lanes за iOS и Android, можете да създадете единен CI/CD процес за кросс-платформено приложение. Използвайте платформени блокове platform :ios и platform :android за групиране на платформено-специфични lanes и ги извиквайте от общ orchestrator lane, който управлява реда на изпълнение.

Най-добри практики за писане на lanes

При писане на lanes се препоръчва спазването на набор от практики, които осигуряват четимост, поддържаемост и надеждност на сценариите. Първото правило — всеки lane трябва да изпълнява една задача. Ако lane прави твърде много, разделете го на няколко lanes и private lanes.

Второто правило — именуването на lanes трябва да бъде глагол или глаголна фраза: build, deploy, test, upload_screenshots. Избягвайте абстрактни имена като process или do_all. Използвайте долни черти за разделяне на думите в името на lane.

Третото правило — обработвайте грешките изрично. Използвайте UI.user_error! за ясни съобщения за проблеми. Не разчитайте на стандартните съобщения за грешки на Fastlane — дайте на разработчика контекст: „Файлът GoogleService-Info.plist не е намерен — добавете го към проекта“ вместо „File not found“.

Четвъртото правило — тествайте lanes локално преди стартиране на CI/CD. Fastlane поддържа режим на сухо изпълнение (dry-run) чрез флага --dry-run, който показва кои действия ще бъдат изпълнени без действително стартиране. Използвайте fastlane run_test за изолирано тестване на отделни lanes преди интеграция.

Документиране на lanes

Документирането на всеки lane е важна практика за екипна разработка. Fastlane поддържа автоматично генериране на документация от desc блока, поставен преди декларацията на lane. Текстът от desc се показва при стартиране на fastlane lanes и fastlane list, помагайки на разработчиците да разберат предназначението на всеки сценарий без да четат изходния код на Fastfile.

За документиране на параметри използвайте Ruby коментари с описание на очакваните стойности. Fastlane може да генерира README.md с пълен списък на lanes и тяхното описание чрез командата fastlane generate_docs, което е удобно за адаптиране на нови членове на екипа към CI/CD процесите на проекта.