CocoaPods Trunk: มันคืออะไร การเผยแพร่ไลบรารีผ่าน Trunk

CocoaPods Trunk คืออะไร?

CocoaPods Trunk คือโครงสร้างพื้นฐานเซิร์ฟเวอร์ที่เปิดตัวในปี 2015 สำหรับการเผยแพร่ไลบรารี pod แบบรวมศูนย์ ก่อน Trunk แต่ละ pod ถูกแจกจ่ายผ่าน Git repository: นักพัฒนาต้องสร้าง repository สาธารณะ เพิ่มไฟล์ podspec และส่ง Pull Request ไปยัง repository กลาง CocoaPods/Specs วิธีการนี้ต้องมีการตรวจสอบด้วยตนเองและทำให้เกิดความล่าช้าในการเผยแพร่อัปเดต

Trunk แก้ปัญหาเหล่านี้โดยการให้ API แบบรวมสำหรับการเผยแพร่ อัปเดต และจัดการ pod บริการประกอบด้วยสี่องค์ประกอบหลัก:

• การยืนยันตัวตน — การลงทะเบียนพร้อมการยืนยันทางอีเมลและการจัดการโทเค็นเซสชัน นักพัฒนาแต่ละคนได้รับโทเค็นเฉพาะที่เชื่อมโยงกับบัญชีและอุปกรณ์ของตน
• การตรวจสอบ — การตรวจสอบ podspec โดยอัตโนมัติก่อนเผยแพร่ รวมถึงการวิเคราะห์ไวยากรณ์ การ linting การพึ่งพา และการตรวจสอบความเข้ากันได้ของแพลตฟอร์ม
• การโฮสต์ — การจัดเก็บข้อมูลเมตาและเวอร์ชันของ pod บนเซิร์ฟเวอร์ของ CocoaPods ซอร์สโค้ดยังคงอยู่ใน Git repository ของนักพัฒนา ในขณะที่ Trunk เก็บเฉพาะไฟล์ podspec และลิงก์
• การจัดการการเข้าถึง — ความสามารถในการเพิ่มและลบเจ้าของ pod โอนสิทธิ์การเผยแพร่ ทำเครื่องหมาย pod ว่าล้าสมัย

สถาปัตยกรรมของ Trunk สร้างขึ้นบนสแต็ก Ruby on Rails พร้อมฐานข้อมูล PostgreSQL บริการใช้ HTTP API ในรูปแบบ JSON สำหรับการดำเนินการทั้งหมด และไคลเอ็นต์ CLI pod trunk เป็นส่วนหนึ่งของการแจกจ่าย CocoaPods ซึ่งติดตั้งพร้อมกับ gem หลัก cocoapods

จนถึงปัจจุบัน มี pod มากกว่า 100,000 ตัวที่เผยแพร่ผ่าน Trunk โดยมียอดดาวน์โหลดรวมเกิน 50 พันล้านครั้ง บริการประมวลผลคำขอเผยแพร่และอัปเดตนับพันรายการต่อวันจากนักพัฒนาทั่วโลก

การลงทะเบียนและการยืนยันตัวตน

ก่อนเผยแพร่ pod คุณต้องลงทะเบียนกับ Trunk กระบวนการประกอบด้วยขั้นตอนเดียว — คำสั่ง pod trunk register:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, การพัฒนา iOS'

หลังจากรันคำสั่ง ลิงก์ยืนยันจะถูกส่งไปยังอีเมลที่ระบุ การคลิกลิงก์จะเปิดใช้งานบัญชีและสร้างโทเค็นเซสชันที่เก็บไว้ในเชนคีย์ของระบบ (Keychain บน macOS, gnome-keyring หรือเทียบเท่าบน Linux) โทเค็นจะถูกใช้โดยอัตโนมัติในการดำเนินการ pod trunk ทั้งหมดที่ตามมา

พารามิเตอร์ --description เป็นทางเลือกแต่แนะนำ — ช่วยระบุเซสชันเมื่อดูเซสชันที่ใช้งานอยู่ผ่าน pod trunk me หากคุณทำงานจากหลายเครื่อง (เวิร์กสเตชัน, เซิร์ฟเวอร์ CI) คำอธิบายจะช่วยแยกแยะเซสชันหนึ่งจากอีกเซสชันหนึ่ง

ในการตรวจสอบสถานะการยืนยันตัวตน ให้ใช้คำสั่ง:

pod trunk me

ผลลัพธ์แสดงอีเมล ชื่อ รายการ pod ของคุณ (หากเคยเผยแพร่แล้ว) และเซสชันที่ใช้งานอยู่ ตัวอย่างผลลัพธ์:

  - 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, การพัฒนา iOS

บนเซิร์ฟเวอร์ CI (GitHub Actions, GitLab CI, Jenkins) การยืนยันตัวตนทำผ่านโทเค็นที่ส่งผ่านตัวแปรสภาพแวดล้อม COCOAPODS_TRUNK_TOKEN สามารถรับโทเค็นได้ด้วยคำสั่ง:

pod trunk me --token-only

โทเค็นนี้ถูกเก็บไว้ในการตั้งค่า CI เป็นตัวแปรลับ และใช้ในขั้นตอนการเผยแพร่โดยไม่ต้องลงทะเบียนซ้ำ ตัวอย่างสำหรับ GitHub Actions:

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

สำคัญ: โทเค็นให้สิทธิ์เข้าถึงเต็มรูปแบบในการจัดการ pod ที่เชื่อมโยงกับบัญชี อย่าเผยแพร่ใน repositories สาธารณะหรือแชร์กับบุคคลที่สาม หากถูกบุกรุก สามารถเพิกถอนโทเค็นได้ผ่าน pod trunk remove-session หรือลบเซสชันทั้งหมดผ่านแผงควบคุมบนเว็บไซต์ CocoaPods

การเตรียม podspec

ไฟล์ podspec (.podspec หรือ .podspec.json) คือแมนิเฟสต์ของไลบรารีที่ประกอบด้วยข้อมูลเมตา การพึ่งพา ข้อมูลแพลตฟอร์ม และรายละเอียดซอร์สโค้ด Trunk ใช้ไฟล์นี้สำหรับการตรวจสอบและการลงทะเบียน pod podspec ขั้นต่ำสำหรับการเผยแพร่มีลักษณะดังนี้:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'คำอธิบายสั้น ๆ ของไลบรารี'
  s.description  = 'คำอธิบายโดยละเอียดพร้อมคำอธิบายความสามารถ'
  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

ฟิลด์สำคัญของ podspec:

• name — ชื่อของ pod ต้องไม่ซ้ำกันในทะเบียน Trunk ชื่อจะถูกลงทะเบียนตามลำดับก่อนหลัง — หากชื่อถูกใช้แล้ว การเผยแพร่จะถูกปฏิเสธ
• version — เวอร์ชันเชิงความหมายในรูปแบบ MAJOR.MINOR.PATCH Trunk ไม่ยอมรับการเผยแพร่ซ้ำของเวอร์ชันเดียวกัน — ต้องเพิ่มหมายเลข
• source — ลิงก์ไปยัง Git repository และแท็ก Trunk ไม่เก็บซอร์สโค้ด ดังนั้น repository ต้องพร้อมสำหรับการโคลน
• platform — แพลตฟอร์มเป้าหมาย (iOS, macOS, tvOS, watchOS) และเวอร์ชัน SDK ขั้นต่ำ
• license — ประเภทใบอนุญาต แนะนำให้ระบุ MIT, Apache-2.0, BSD หรือใบอนุญาตโอเพนซอร์สอื่น ๆ

ก่อนเผยแพร่ ตรวจสอบความถูกต้องของ podspec ด้วย linter:

pod lib lint MyLibrary.podspec

Linter ตรวจสอบไวยากรณ์ ฟิลด์ที่จำเป็น ความถูกต้องของเส้นทางไฟล์ และความสามารถในการแก้ไขการพึ่งพา หากในกระบวนการ linting ใช้แหล่งข้อมูลส่วนตัว ให้เพิ่มแฟล็ก --sources เพื่อข้ามการดาวน์โหลดเครือข่าย (ตรวจสอบเฉพาะในเครื่อง) ให้ใช้แฟล็ก --local-only

การเผยแพร่ผ่าน pod trunk push

คำสั่งหลักสำหรับการเผยแพร่ pod คือ pod trunk push มันส่งไฟล์ podspec ไปยังเซิร์ฟเวอร์ Trunk ซึ่งผ่านการตรวจสอบอย่างสมบูรณ์และลงทะเบียนในทะเบียนสาธารณะ ไวยากรณ์:

pod trunk push MyLibrary.podspec

แฟล็ก --allow-warnings อนุญาตให้เผยแพร่เมื่อมีคำเตือน โดยค่าเริ่มต้น คำเตือนใด ๆ จะบล็อกการเผยแพร่ หากไลบรารีของคุณมีคำเตือนที่ทราบซึ่งไม่ส่งผลต่อการทำงาน คุณสามารถใช้แฟล็กนี้ได้ สำคัญ: ข้อผิดพลาดจะบล็อกการเผยแพร่เสมอ โดยไม่คำนึงถึงแฟล็ก

แฟล็ก --synchronous ทำให้คำขอเป็นแบบซิงโครนัส — เทอร์มินัลรอให้การตรวจสอบฝั่งเซิร์ฟเวอร์เสร็จสมบูรณ์ โดยค่าเริ่มต้น คำสั่งจะคืนการควบคุมทันทีหลังจากส่ง และเซิร์ฟเวอร์ประมวลผลการเผยแพร่แบบอะซิงโครนัส โหมดซิงโครนัสมีประโยชน์ใน CI/CD เมื่อขั้นตอนถัดไปของ pipeline ขึ้นอยู่กับความสำเร็จของการเผยแพร่

แฟล็ก --skip-import-validation ข้ามการตรวจสอบการนำเข้าไลบรารีไปยังโปรเจกต์ทดสอบ ซึ่งช่วยเร่งการเผยแพร่แต่ไม่รับประกันว่าไลบรารีจะคอมไพล์จริง ใช้แฟล็กนี้เฉพาะเมื่อคุณมั่นใจในความถูกต้องของการ build

ตัวอย่างการเผยแพร่ด้วยตัวเลือกทั่วไป:

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

หลังจากการเผยแพร่สำเร็จ Trunk ส่งคืน JSON พร้อมรายละเอียด:

  Congrats

  MyLibrary (0.1.0) successfully published

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

ไลบรารีพร้อมให้ติดตั้งผ่าน Podfile ในโปรเจกต์ iOS หรือ macOS ใด ๆ โดยปกติ ดัชนีการค้นหาของ CocoaPods จะอัปเดตภายในไม่กี่นาที แต่ในกรณีที่พบไม่บ่อย การจัดทำดัชนีอาจใช้เวลาถึงหนึ่งชั่วโมง

ข้อจำกัดสำคัญ: เวอร์ชัน pod ที่เผยแพร่แล้ว ไม่สามารถลบได้ เพื่อป้องกันไม่ให้โปรเจกต์ที่ใช้เวอร์ชันนี้อยู่เสียหาย หากการเผยแพร่มีข้อผิดพลาด คุณสามารถเผยแพร่เวอร์ชันถัดไปพร้อมการแก้ไขได้ แต่ไม่สามารถย้อนกลับได้ ข้อยกเว้นคือ pod trunk delete ซึ่งมีให้เฉพาะเจ้าหน้าที่ CocoaPods และใช้ในกรณีร้ายแรง (การละเมิดใบอนุญาต, โค้ดที่เป็นอันตราย)

การจัดการรุ่นและการเข้าถึง

CocoaPods Trunk มีคำสั่งหลายคำสั่งสำหรับดูแล pod ที่เผยแพร่แล้ว:

การเพิ่มเจ้าของ

ในการโอนสิทธิ์การเผยแพร่ pod ให้นักพัฒนาคนอื่น ให้ใช้คำสั่ง:

pod trunk add-owner MyLibrary developer@email.com

หลังจากการดำเนินการ เจ้าของใหม่จะได้รับสิทธิ์เข้าถึงเต็มรูปแบบในการจัดการ pod: การเผยแพร่เวอร์ชันใหม่ การเพิ่มและลบเจ้าของอื่น การทำเครื่องหมาย pod ว่าล้าสมัย ผู้ใช้ Trunk ที่ลงทะเบียนแล้วทุกคนสามารถเป็นเจ้าของได้ — การลงทะเบียนล่วงหน้าเป็นสิ่งจำเป็น

การลบเจ้าของ

หากนักพัฒนาออกจากโปรเจกต์หรือไม่ควรมีสิทธิ์เข้าถึง pod อีกต่อไป:

pod trunk remove-owner MyLibrary developer@email.com

เฉพาะเจ้าของปัจจุบันเท่านั้นที่สามารถลบเจ้าของได้ ไม่สามารถลบเจ้าของคนสุดท้ายของ pod ได้ — ต้องเพิ่มเจ้าของใหม่ก่อน ซึ่งป้องกันไม่ให้ pod ไร้เจ้าของและถูกทอดทิ้ง

การทำเครื่องหมาย pod ว่าล้าสมัย

หากไลบรารีไม่ได้รับการดูแลอีกต่อไป คุณสามารถทำเครื่องหมายว่าล้าสมัย (deprecated) ซึ่งไม่ได้ลบ pod ออกจากทะเบียน แต่เพิ่มคำเตือนให้ผู้ใช้ระหว่างการติดตั้ง:

pod trunk deprecate MyLibrary

คุณสามารถระบุ pod ทดแทนได้:

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

เมื่อติดตั้ง pod ที่ล้าสมัย CocoaPods จะแสดงคำเตือนในเทอร์มินัลและแนะนำให้เปลี่ยนไปใช้ pod ทดแทนที่ระบุ นี่เป็นวิธีที่ถูกต้องในการยุติการสนับสนุนไลบรารีโดยไม่ทำให้การ build ของโปรเจกต์ที่มีอยู่เสียหาย

การดูข้อมูล pod

ข้อมูล pod สามารถดูได้ผ่านคำสั่ง pod trunk info:

pod trunk info MyLibrary

คำสั่งแสดงเวอร์ชัน pod ทั้งหมด วันที่เผยแพร่ รายชื่อเจ้าของ และสถานะ (ใช้งานอยู่/ล้าสมัย) หากต้องการดูรายละเอียดของเวอร์ชันเฉพาะ ให้ใช้ pod spec cat MyLibrary 0.1.0

ข้อผิดพลาดและวิธีแก้ไข

เมื่อทำงานกับ Trunk นักพัฒนามักพบข้อผิดพลาดทั่วไป มาดูข้อผิดพลาดที่พบบ่อยที่สุด:

ข้อผิดพลาดการยืนยันตัวตน

อาการ: [!] Authentication failed. You need to register a session first.
สาเหตุ: โทเค็นเซสชันหายไปหรือหมดอายุ โทเค็นมีอายุการใช้งานจำกัด (ค่าเริ่มต้น 30 วันโดยไม่มีกิจกรรม)
วิธีแก้ไข: รัน pod trunk register your@email.com 'Your Name' อีกครั้ง หากคุณใช้ CI ให้ตรวจสอบตัวแปรสภาพแวดล้อม COCOAPODS_TRUNK_TOKEN ว่าอัปเดตหรือไม่ และสร้างโทเค็นใหม่หากจำเป็น

ข้อขัดแย้งของเวอร์ชัน

อาการ: [!] You have already pushed version 0.1.0 for MyLibrary.
สาเหตุ: พยายามเผยแพร่เวอร์ชันที่มีอยู่ซ้ำ Trunk ไม่อนุญาตให้เขียนทับเวอร์ชัน
วิธีแก้ไข: เพิ่มเวอร์ชันใน podspec ตามการกำหนดเวอร์ชันเชิงความหมาย หากคุณทำผิดใน podspec ให้เผยแพร่เวอร์ชันถัดไปพร้อมการแก้ไข

ข้อผิดพลาดการตรวจสอบ podspec

อาการ: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
สาเหตุ: เส้นทางไปยังไฟล์ต้นฉบับในฟิลด์ source_files ไม่ถูกต้อง
วิธีแก้ไข: ตรวจสอบเส้นทางใน podspec รัน pod lib lint ในเครื่องจนกว่าข้อผิดพลาดทั้งหมดจะได้รับการแก้ไข จากนั้นเผยแพร่ซ้ำ ใช้รูปแบบ glob: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift

การเชื่อมต่อหมดเวลา

อาการ: [!] Connection to trunk.cocoapods.org failed. Timeout.
สาเหตุ: ปัญหาเครือข่ายหรือเซิร์ฟเวอร์ Trunk ไม่พร้อมใช้งานชั่วคราว
วิธีแก้ไข: ตรวจสอบความพร้อมใช้งานของเซิร์ฟเวอร์: curl -I https://trunk.cocoapods.org หากเซิร์ฟเวอร์ตอบสนอง ให้ลองอีกครั้งในอีกไม่กี่นาที IP ของคุณอาจถูกบล็อก — ลองจากการเชื่อมต่ออื่นหรือผ่าน VPN

ไม่มีสิทธิ์เข้าถึง pod

อาการ: [!] You do not have permission to push to MyLibrary.
สาเหตุ: คุณไม่ใช่เจ้าของ pod ซึ่งเกิดขึ้นหากมีคนลงทะเบียน pod ด้วยชื่อนั้นไว้แล้ว
วิธีแก้ไข: ติดต่อเจ้าของ pod ปัจจุบัน (สามารถดูได้ผ่าน pod trunk info MyLibrary) และขอให้พวกเขาเพิ่มคุณผ่าน pod trunk add-owner หากชื่อ pod ถูกใช้แล้ว ให้พิจารณาชื่ออื่น