CocoaPods Trunk: nó là gì, xuất bản thư viện qua Trunk

CocoaPods Trunk là gì?

CocoaPods Trunk là cơ sở hạ tầng máy chủ được ra mắt vào năm 2015 để xuất bản tập trung các thư viện pod. Trước Trunk, mỗi pod được phân phối qua kho Git: nhà phát triển phải tạo kho lưu trữ công khai, thêm tệp podspec và gửi Pull Request đến kho lưu trữ trung tâm CocoaPods/Specs. Cách tiếp cận này yêu cầu kiểm duyệt thủ công và gây ra sự chậm trễ khi xuất bản các bản cập nhật.

Trunk đã giải quyết những vấn đề này bằng cách cung cấp API thống nhất để xuất bản, cập nhật và quản lý pod. Dịch vụ bao gồm bốn thành phần chính:

• Xác thực — đăng ký với xác nhận email và quản lý token phiên. Mỗi nhà phát triển nhận được một token duy nhất được liên kết với tài khoản và thiết bị của họ.
• Xác nhận — kiểm tra tự động podspec trước khi xuất bản, bao gồm phân tích cú pháp, linting phụ thuộc và kiểm tra tương thích nền tảng.
• Lưu trữ — lưu trữ siêu dữ liệu và phiên bản pod trên máy chủ CocoaPods. Mã nguồn vẫn nằm trong kho Git của nhà phát triển, Trunk chỉ lưu trữ tệp podspec và liên kết.
• Quản lý truy cập — khả năng thêm và xóa chủ sở hữu pod, chuyển nhượng quyền xuất bản, đánh dấu pod là không còn được hỗ trợ.

Kiến trúc của Trunk được xây dựng trên nền tảng Ruby on Rails với cơ sở dữ liệu PostgreSQL. Dịch vụ sử dụng API HTTP với định dạng JSON cho tất cả các hoạt động, và máy khách CLI pod trunk là một phần của bản phân phối CocoaPods, được cài đặt cùng với gem chính cocoapods.

Cho đến nay, hơn 100.000 pod đã được xuất bản qua Trunk, với tổng số lượt tải xuống vượt quá 50 tỷ. Dịch vụ xử lý hàng nghìn yêu cầu xuất bản và cập nhật mỗi ngày từ các nhà phát triển trên khắp thế giới.

Đăng ký và xác thực

Trước khi xuất bản pod, bạn phải đăng ký với Trunk. Quy trình bao gồm một bước duy nhất — lệnh pod trunk register:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, phát triển iOS'

Sau khi thực thi lệnh, một liên kết xác nhận được gửi đến email đã chỉ định. Nhấp vào liên kết sẽ kích hoạt tài khoản và tạo token phiên được lưu trữ trong chuỗi khóa hệ thống (Keychain trên macOS, gnome-keyring hoặc tương đương trên Linux). Token được tự động sử dụng cho tất cả các thao tác pod trunk tiếp theo.

Tham số --description là tùy chọn nhưng được khuyến nghị — nó giúp xác định phiên khi xem các phiên hoạt động qua pod trunk me. Nếu bạn làm việc từ nhiều máy (máy trạm, máy chủ CI), mô tả sẽ giúp phân biệt phiên này với phiên khác.

Để kiểm tra trạng thái xác thực, sử dụng lệnh:

pod trunk me

Đầu ra hiển thị email, tên, danh sách pod của bạn (nếu đã xuất bản) và các phiên hoạt động. Ví dụ về kết quả:

  - Name: Your Name
  - Email: your@email.com
  - Since: 2024-03-15 10:30 UTC
  - Pods:
    - MyLibrary
    - AnotherPod
  - Sessions:
    - 2024-03-15 10:30 UTC - MacBook Pro, phát triển iOS

Trên máy chủ CI (GitHub Actions, GitLab CI, Jenkins), xác thực được thực hiện qua token được truyền qua biến môi trường COCOAPODS_TRUNK_TOKEN. Token có thể được lấy bằng lệnh:

pod trunk me --token-only

Token này được lưu trữ trong cài đặt CI như một biến bí mật và được sử dụng trong bước xuất bản mà không cần đăng ký lại. Ví dụ cho GitHub Actions:

env:
  COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}

Quan trọng: token cung cấp quyền truy cập đầy đủ để quản lý các pod được liên kết với tài khoản. Không bao giờ công bố nó trong các kho lưu trữ công khai hoặc chia sẻ với bên thứ ba. Nếu bị xâm phạm, token có thể bị thu hồi qua pod trunk remove-session hoặc xóa tất cả phiên qua bảng điều khiển trên trang web CocoaPods.

Chuẩn bị podspec

Tệp podspec (.podspec hoặc .podspec.json) là bảng kê khai thư viện chứa siêu dữ liệu, phụ thuộc, thông tin nền tảng và mã nguồn. Trunk sử dụng tệp này để xác nhận và đăng ký pod. Một podspec tối thiểu để xuất bản trông như sau:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Mô tả ngắn về thư viện'
  s.description  = 'Mô tả chi tiết kèm giải thích tính năng'
  s.homepage     = 'https://github.com/username/MyLibrary'
  s.license      = { :type => 'MIT', :file => 'LICENSE' }
  s.author       = { 'Your Name' => 'your@email.com' }
  s.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => s.version.to_s }
  s.source_files = 'Sources/**/*.{swift,h,m}'
  s.platform     = :ios, '12.0'
  s.swift_version = '5.7'
end

Các trường chính của podspec:

• name — tên pod, phải là duy nhất trong sổ đăng ký Trunk. Tên được đăng ký theo nguyên tắc ai đến trước được phục vụ trước — nếu tên đã được sử dụng, việc xuất bản sẽ bị từ chối.
• version — phiên bản ngữ nghĩa theo định dạng MAJOR.MINOR.PATCH. Trunk không chấp nhận xuất bản lại cùng một phiên bản — phải tăng số.
• source — liên kết đến kho Git và thẻ. Trunk không lưu trữ mã nguồn, do đó kho lưu trữ phải có sẵn để sao chép.
• platform — nền tảng mục tiêu (iOS, macOS, tvOS, watchOS) và phiên bản SDK tối thiểu.
• license — loại giấy phép. Khuyến nghị chỉ định MIT, Apache-2.0, BSD hoặc giấy phép mã nguồn mở khác.

Trước khi xuất bản, hãy kiểm tra tính chính xác của podspec bằng trình lint:

pod lib lint MyLibrary.podspec

Trình lint kiểm tra cú pháp, các trường bắt buộc, tính chính xác của đường dẫn tệp và khả năng giải quyết phụ thuộc. Nếu trong quá trình lint sử dụng nguồn riêng tư, cờ --sources được thêm vào. Để bỏ qua tải xuống mạng (chỉ kiểm tra cục bộ), sử dụng cờ --local-only.

Xuất bản qua pod trunk push

Lệnh chính để xuất bản pod là pod trunk push. Nó gửi tệp podspec đến máy chủ Trunk, nơi nó trải qua xác nhận đầy đủ và được đăng ký trong sổ đăng ký công khai. Cú pháp:

pod trunk push MyLibrary.podspec

Cờ --allow-warnings cho phép xuất bản khi có cảnh báo. Theo mặc định, bất kỳ cảnh báo nào cũng chặn xuất bản. Nếu thư viện của bạn có các cảnh báo đã biết không ảnh hưởng đến chức năng, bạn có thể sử dụng cờ này. Quan trọng: lỗi luôn chặn xuất bản, bất kể cờ nào.

Cờ --synchronous làm cho yêu cầu đồng bộ — terminal đợi hoàn tất xác nhận trên máy chủ. Theo mặc định, lệnh trả lại quyền điều khiển ngay sau khi gửi và máy chủ xử lý xuất bản không đồng bộ. Chế độ đồng bộ hữu ích trong CI/CD khi bước tiếp theo của pipeline phụ thuộc vào sự thành công của việc xuất bản.

Cờ --skip-import-validation bỏ qua kiểm tra nhập thư viện vào dự án thử nghiệm. Điều này tăng tốc xuất bản nhưng không đảm bảo thư viện thực sự biên dịch được. Chỉ sử dụng cờ này nếu bạn chắc chắn về tính chính xác của bản dựng.

Ví dụ xuất bản với các tùy chọn điển hình:

pod trunk push MyLibrary.podspec \
  --allow-warnings \
  --synchronous \
  --skip-import-validation

Sau khi xuất bản thành công, Trunk trả về JSON với chi tiết:

  Congrats

  MyLibrary (0.1.0) successfully published

  Pod URL: https://cocoapods.org/pods/MyLibrary

Thư viện có sẵn để cài đặt qua Podfile trong bất kỳ dự án iOS hoặc macOS nào. Thông thường, chỉ mục tìm kiếm CocoaPods được cập nhật trong vòng vài phút, nhưng trong một số trường hợp hiếm, việc lập chỉ mục có thể mất đến một giờ.

Hạn chế quan trọng: một phiên bản pod đã xuất bản không thể bị xóa. Điều này để ngăn chặn việc phá vỡ các dự án đã sử dụng phiên bản này. Nếu việc xuất bản có lỗi, bạn có thể xuất bản phiên bản tiếp theo với bản sửa lỗi, nhưng không thể khôi phục. Ngoại lệ là pod trunk delete, chỉ có sẵn cho nhân viên CocoaPods và được sử dụng trong các trường hợp cực đoan (vi phạm giấy phép, mã độc hại).

Quản lý bản phát hành và truy cập

CocoaPods Trunk cung cấp một số lệnh để quản trị các pod đã xuất bản:

Thêm chủ sở hữu

Để chuyển nhượng quyền xuất bản pod cho nhà phát triển khác, sử dụng lệnh:

pod trunk add-owner MyLibrary developer@email.com

Sau khi thực thi, chủ sở hữu mới nhận được quyền truy cập đầy đủ để quản lý pod: xuất bản phiên bản mới, thêm và xóa chủ sở hữu khác, đánh dấu pod là không còn được hỗ trợ. Bất kỳ người dùng Trunk đã đăng ký nào cũng có thể là chủ sở hữu — đăng ký trước là bắt buộc.

Xóa chủ sở hữu

Nếu nhà phát triển đã rời khỏi dự án hoặc không còn nên có quyền truy cập vào pod:

pod trunk remove-owner MyLibrary developer@email.com

Chỉ chủ sở hữu hiện tại mới có thể xóa chủ sở hữu. Không thể xóa chủ sở hữu cuối cùng của pod — trước tiên phải thêm chủ sở hữu mới. Điều này ngăn pod trở nên vô chủ và bị bỏ rơi.

Đánh dấu pod là không còn được hỗ trợ

Nếu thư viện không còn được bảo trì, bạn có thể đánh dấu nó là không còn được hỗ trợ (deprecated). Điều này không xóa pod khỏi sổ đăng ký, nhưng thêm cảnh báo cho người dùng khi cài đặt:

pod trunk deprecate MyLibrary

Tùy chọn, bạn có thể chỉ định một pod thay thế:

pod trunk deprecate MyLibrary --in-favor-of=NewLibrary

Khi cài đặt pod không còn được hỗ trợ, CocoaPods hiển thị cảnh báo trong terminal và khuyến nghị chuyển sang thay thế đã chỉ định. Đây là cách chính xác để kết thúc hỗ trợ thư viện mà không phá vỡ bản dựng của các dự án hiện có.

Xem thông tin pod

Thông tin pod có sẵn qua lệnh pod trunk info:

pod trunk info MyLibrary

Lệnh hiển thị tất cả các phiên bản pod, ngày xuất bản, danh sách chủ sở hữu và trạng thái (hoạt động/không còn được hỗ trợ). Để xem chi tiết của một phiên bản cụ thể, sử dụng pod spec cat MyLibrary 0.1.0.

Lỗi và giải pháp

Khi làm việc với Trunk, các nhà phát triển thường gặp phải các lỗi điển hình. Hãy xem xét những lỗi phổ biến nhất:

Lỗi xác thực

Triệu chứng: [!] Authentication failed. You need to register a session first.
Nguyên nhân: Token phiên bị thiếu hoặc hết hạn. Token có thời hạn hiệu lực giới hạn (mặc định 30 ngày không hoạt động).
Giải pháp: Thực hiện lại pod trunk register your@email.com 'Your Name'. Nếu bạn sử dụng CI, hãy kiểm tra biến môi trường COCOAPODS_TRUNK_TOKEN có cập nhật không và tạo token mới nếu cần.

Xung đột phiên bản

Triệu chứng: [!] You have already pushed version 0.1.0 for MyLibrary.
Nguyên nhân: Cố gắng xuất bản lại phiên bản đã tồn tại. Trunk không cho phép ghi đè phiên bản.
Giải pháp: Tăng phiên bản trong podspec theo quản lý phiên bản ngữ nghĩa. Nếu bạn đã sai trong podspec, hãy xuất bản phiên bản tiếp theo với bản sửa lỗi.

Lỗi xác nhận podspec

Triệu chứng: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Nguyên nhân: Đường dẫn không chính xác đến tệp nguồn trong trường source_files.
Giải pháp: Kiểm tra đường dẫn trong podspec, thực thi pod lib lint cục bộ cho đến khi giải quyết tất cả lỗi, sau đó lặp lại xuất bản. Sử dụng mẫu glob: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Hết thời gian chờ kết nối

Triệu chứng: [!] Connection to trunk.cocoapods.org failed. Timeout.
Nguyên nhân: Sự cố mạng hoặc máy chủ Trunk tạm thời không khả dụng.
Giải pháp: Kiểm tra khả dụng của máy chủ: curl -I https://trunk.cocoapods.org. Nếu máy chủ phản hồi, hãy lặp lại lệnh sau vài phút. IP của bạn có thể bị chặn — hãy thử từ kết nối khác hoặc qua VPN.

Không có quyền truy cập vào pod

Triệu chứng: [!] You do not have permission to push to MyLibrary.
Nguyên nhân: Bạn không phải là chủ sở hữu của pod. Điều này xảy ra nếu ai đó đã đăng ký pod với tên đó.
Giải pháp: Liên hệ với chủ sở hữu pod hiện tại (tìm hiểu qua pod trunk info MyLibrary) và yêu cầu họ thêm bạn qua pod trunk add-owner. Nếu tên pod đã được sử dụng, hãy xem xét tên thay thế.