Lane — khái niệm, cách tạo và sử dụng trong Fastlane

Lane trong Fastlane là gì

Lane — là khối xây dựng cơ bản của Fastlane, định nghĩa một kịch bản tự động hóa có tên. Mỗi lane mô tả một chuỗi các hành động (actions) được thực thi để đạt được một mục tiêu cụ thể: xây dựng ứng dụng, chạy kiểm thử, tải build lên cửa hàng hoặc cấu hình môi trường. Lane được khai báo trong Fastfile và chạy bằng lệnh fastlane [tên_lane] từ thư mục gốc của dự án.

Khái niệm lane được vay mượn từ Ruby DSL và đảm bảo tính dễ đọc của kịch bản. Nhà phát triển thấy toàn bộ quy trình CI/CD như một chuỗi các lời gọi actions với tên và tham số dễ hiểu. Lane có thể đơn giản (một lệnh) hoặc phức tạp (rẽ nhánh, vòng lặp, gọi các lane khác).

Mỗi lane sau khi thực thi trả về một kết quả — một đối tượng chứa trạng thái thực thi và dữ liệu từ các actions. Kết quả có thể được sử dụng trong các lane khác hoặc truyền cho hệ thống CI/CD để đưa ra quyết định. Nếu bất kỳ action nào trong lane kết thúc với lỗi, việc thực thi lane sẽ dừng lại và khối error được gọi.

Cú pháp lane: khai báo và chạy

Cú pháp khai báo lane tuân theo một mẫu đơn giản của Ruby DSL: từ khóa lane, tên kịch bản dưới dạng symbol Ruby, khối do ... end với phần thân kịch bản. Tên lane phải là duy nhất trong phạm vi nền tảng và bao gồm các chữ cái, chữ số và dấu gạch dưới.

Việc chạy lane được thực hiện qua dòng lệnh: fastlane build (cho lane có tên :build) hoặc bundle exec fastlane build (nếu Fastlane được cài qua Bundler). Đối với các lane theo nền tảng, sử dụng fastlane ios build hoặc fastlane android build.

# Khai báo lane đơn giản
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

# Chạy: fastlane build_and_deploy

Lane có thể chứa logic điều kiện dựa trên tham số hoặc biến môi trường. Sử dụng if/unless để bỏ qua các bước trong những điều kiện nhất định. Cũng có thể sử dụng vòng lặp each để xử lý mảng, tiện cho việc xây dựng nhiều target hoặc scheme ứng dụng trong một lane.

Giá trị trả về từ lane

Lane có thể trả về một giá trị mà mã gọi có thể truy cập được. Để trả về, sử dụng return thông thường của Ruby hoặc biểu thức cuối cùng trong khối lane. Giá trị trả về có thể là chuỗi, số, hash hoặc kết quả của action. Điều này cho phép sử dụng kết quả của một lane trong lane khác để đưa ra quyết định.

Ví dụ, lane :get_version có thể trả về phiên bản hiện tại của ứng dụng từ Info.plist, và lane :deploy sử dụng nó để tạo thông báo trong Slack. Giá trị trả về đặc biệt hữu ích trong các private lane, nơi kết quả cần thiết cho xử lý tiếp theo trong lane gọi.

Tham số lane: truyền và xử lý

Tham số lane làm cho các kịch bản trở nên linh hoạt và có thể tái sử dụng. Lane nhận tham số qua hash options, được truyền khi chạy từ dòng lệnh: fastlane deploy scheme:AppStore version:2.1.0. Bên trong lane, các tham số có thể truy cập qua options[:scheme] và options[:version].

Đối với tham số bắt buộc, hãy kiểm tra sự tồn tại của giá trị ở đầu lane và gọi UI.user_error! với thông báo rõ ràng. Đối với tham số tùy chọn, đặt giá trị mặc định qua toán tử ||. Fastlane cũng hỗ trợ tham số có kiểu thông qua phương thức options với chỉ định kiểu, giá trị mặc định và mô tả.

# Lane với xử lý tham số
lane :deploy do |options|
  scheme = options[:scheme]
  version = options[:version] || '1.0.0'
  beta = options[:beta] || false

  UI.user_error!("Chưa chỉ định 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

# Chạy: fastlane deploy scheme:MyApp beta:true version:2.1.0

Để làm việc với biến môi trường trong lane, sử dụng ENV['VARIABLE_NAME']. Fastlane tự động tải các tệp .env từ thư mục fastlane. Đây là cách tiêu chuẩn để truyền dữ liệu nhạy cảm — khóa API, mật khẩu và token — trong môi trường CI/CD mà không lưu trữ chúng trong Fastfile.

Xác thực tham số

Để lane hoạt động đáng tin cậy, cần xác thực tham số đầu vào. Sử dụng UI.user_error! với mô tả vấn đề nếu tham số bắt buộc bị thiếu hoặc có kiểu không đúng. Fastlane cung cấp phương thức options, cho phép đặt kiểu (String, Boolean, Integer, Array), giá trị mặc định và mô tả cho mỗi tham số — xác thực được thực hiện tự động khi chạy lane.

Ngoài ra có thể sử dụng kiểm tra qua khối verify: verify do |value| value.length > 0 end cho tham số chuỗi. Khi định dạng không đúng, Fastlane hiển thị thông báo rõ ràng với định dạng mong đợi và giá trị đã truyền, giúp dễ dàng gỡ lỗi trong môi trường CI/CD.

Kết hợp lane: before_all, after_all và xử lý lỗi

Fastlane cung cấp các hook vòng đời để thực thi mã trước và sau mỗi lane. Khối before_all thực thi trước mỗi lane trên nền tảng cụ thể hoặc toàn cục. Khối after_all thực thi sau khi lane hoàn thành thành công. Khối error thực thi khi có lỗi xảy ra trong lane.

Các hook cho phép tập trung hóa logic lặp lại: cài đặt phụ thuộc trong before_all, gửi thông báo trong after_all, dọn dẹp tệp tạm thời và thông báo lỗi trong khối error. Điều này giảm trùng lặp mã và làm cho các lane sạch hơn.

# Hook vòng đời lane
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} đã thực hiện thành công")
end

error do |lane, exception|
  slack(
    message: "Lane #{lane} thất bại với lỗi: #{exception}",
    success: false
  )
end

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

Khối error nhận hai đối số: tên lane (symbol) và đối tượng ngoại lệ. Bên trong khối, bạn có thể gửi thông báo trong Slack, ghi log vào tệp hoặc chạy kịch bản phục hồi thay thế. Nếu khối error kết thúc thành công, Fastlane không coi bản build là thất bại ở cấp độ CI/CD.

Private lanes và tái sử dụng

Private lane — là lane được khai báo qua private_lane thay vì lane, không hiển thị trong danh sách lệnh khả dụng và không thể chạy trực tiếp từ terminal. Private lanes được thiết kế để đóng gói các bước lặp lại được gọi từ nhiều lane công khai.

Private lanes đặc biệt hữu ích cho các chuỗi hành động phức tạp cần được thực thi theo thứ tự nghiêm ngặt. Ví dụ, private lane :setup_signing có thể được gọi từ các lane :build_dev, :build_staging và :build_production với các tham số khác nhau, nhưng tự nó không có ý nghĩa như một lệnh riêng biệt.

# Private lanes để tái sử dụng
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 có thể gọi các private lanes khác, tạo thành một hệ thống phân cấp trừu tượng. Nên giới hạn độ sâu lồng nhau ở mức 2–3 cấp để duy trì tính dễ đọc của Fastfile. Ghi chú cho mỗi private lane bằng comment mô tả mục đích và tham số mong đợi.

Ví dụ lane cho iOS và Android

Hãy xem xét các ví dụ thực tế về lane cho dự án iOS và Android. Lane iOS thường sử dụng scan cho kiểm thử, match cho chứng chỉ, gym cho xây dựng và pilot hoặc deliver cho phân phối. Lane Android sử dụng gradle cho xây dựng, supply cho xuất bản và firebase_test_lab cho kiểm thử đám mây.

// Lane cho CI/CD hoàn chỉnh ứng dụng 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: 'CI/CD iOS hoàn thành thành công')
end

/* Lane cho CI/CD hoàn chỉnh ứng dụng Android */
lane :ci_full_android do
  gradle(task: 'testReleaseUnitTest')
  gradle(task: 'bundleRelease')
  supply(track: 'internal')
end

Bằng cách kết hợp các lane cho iOS và Android, bạn có thể tạo một quy trình CI/CD thống nhất cho ứng dụng đa nền tảng. Sử dụng khối nền tảng platform :ios và platform :android để nhóm các lane cụ thể theo nền tảng, và gọi chúng từ lane orchestrator chung quản lý thứ tự thực thi.

Thực hành tốt nhất khi viết lane

Khi viết lane, nên tuân theo một bộ thực hành đảm bảo tính dễ đọc, khả năng bảo trì và độ tin cậy của kịch bản. Nguyên tắc đầu tiên — mỗi lane nên thực hiện một tác vụ duy nhất. Nếu lane làm quá nhiều việc, hãy chia nó thành nhiều lane và private lanes.

Nguyên tắc thứ hai — đặt tên lane nên là động từ hoặc cụm động từ: build, deploy, test, upload_screenshots. Tránh các tên trừu tượng như process hoặc do_all. Sử dụng dấu gạch dưới để phân cách các từ trong tên lane.

Nguyên tắc thứ ba — xử lý lỗi một cách rõ ràng. Sử dụng UI.user_error! để có thông báo dễ hiểu về vấn đề. Đừng phụ thuộc vào thông báo lỗi mặc định của Fastlane — hãy cung cấp cho nhà phát triển ngữ cảnh: “Không tìm thấy tệp GoogleService-Info.plist — hãy thêm nó vào dự án” thay vì “File not found”.

Nguyên tắc thứ tư — kiểm thử lane cục bộ trước khi chạy trên CI/CD. Fastlane hỗ trợ chế độ dry-run qua cờ --dry-run, hiển thị các actions sẽ được thực thi mà không chạy thực tế. Sử dụng fastlane run_test để kiểm thử riêng lẻ từng lane trước khi tích hợp.

Tài liệu hóa lane

Tài liệu hóa mỗi lane là một thực hành quan trọng cho phát triển nhóm. Fastlane hỗ trợ tạo tài liệu tự động từ khối desc đặt trước khai báo lane. Văn bản desc hiển thị khi chạy fastlane lanes và fastlane list, giúp nhà phát triển hiểu mục đích của mỗi kịch bản mà không cần đọc mã nguồn Fastfile.

Để tài liệu hóa tham số, sử dụng comment Ruby với mô tả giá trị mong đợi. Fastlane có thể tạo README.md với danh sách đầy đủ các lane và mô tả của chúng qua lệnh fastlane generate_docs, tiện cho việc làm quen của thành viên mới với quy trình CI/CD của dự án.