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 برای پردازش آرایه‌ها در دسترس هستند که برای ساخت چندین target یا طرح‌واره اپلیکیشن در یک lane مفید است.

بازگرداندن مقدار از lane

Lane می‌تواند مقداری را بازگرداند که برای کد فراخوانی‌کننده در دسترس خواهد بود. برای بازگرداندن از return استاندارد Ruby یا آخرین عبارت در بلوک 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 و مدیریت خطا

Fastlane قلاب‌های چرخه زندگی را برای اجرای کد قبل و بعد از هر lane ارائه می‌دهد. بلوک before_all قبل از هر lane در یک پلتفرم خاص یا به صورت سراسری اجرا می‌شود. بلوک after_all پس از اتمام موفقیت‌آمیز lane اجرا می‌شود. بلوک error در هر خطایی در داخل lane اجرا می‌شود.

قلاب‌ها امکان متمرکز کردن منطق تکراری را فراهم می‌کنند: نصب وابستگی‌ها در 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 برای کپسوله‌سازی مراحل تکراری که از چندین public lane فراخوانی می‌شوند طراحی شده‌اند.

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 کار زیادی انجام می‌دهد، آن را به چند lane و private lane تقسیم کنید.

قانون دوم — نام‌گذاری 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 پشتیبانی می‌کند که نشان می‌دهد کدام actions بدون اجرای واقعی انجام می‌شوند. از 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 پروژه مفید است.