buf

บุฟ

buf CLI เป็นเครื่องมือที่ดีที่สุดสำหรับการทำงานกับ Protocol Buffers มันมี:

• linter ที่บังคับใช้ตัวเลือกและโครงสร้างการออกแบบ API ที่ดี
• ตัวตรวจจับการเปลี่ยนแปลงที่ขัดข้องซึ่งบังคับใช้ความเข้ากันได้ในระดับซอร์สโค้ดหรือระดับสาย
• ตัวสร้างที่เรียกใช้ปลั๊กอินของคุณตามเทมเพลตที่กำหนดค่าได้
• ฟอร์แมตเตอร์ที่จัดรูปแบบไฟล์ Protobuf ของคุณตามมาตรฐานอุตสาหกรรม
• การบูรณาการกับ Buf Schema Registry รวมถึงการจัดการการพึ่งพาเต็มรูปแบบ

การติดตั้ง

โฮมบรูว์

คุณสามารถติดตั้ง buf โดยใช้ Homebrew (macOS หรือ Linux):

brew install bufbuild/buf/buf

สิ่งนี้จะติดตั้ง:

• buf , protoc-gen-buf-breaking และไบนารี protoc-gen-buf-lint
• สคริปต์การเติมเชลล์สำหรับ Bash, Fish, Powershell และ zsh

วิธีการอื่นๆ

สำหรับวิธีการติดตั้งอื่นๆ โปรดดูเอกสารอย่างเป็นทางการของเรา ซึ่งครอบคลุมถึง:

• กำลังติดตั้ง buf ผ่าน npm
• การติดตั้ง buf บน Windows
• การใช้ buf เป็นอิมเมจ Docker
• การติดตั้งเป็นไบนารี จาก tarball และจากแหล่งที่มาผ่าน GitHub Releases
• การตรวจสอบการเผยแพร่โดยใช้คีย์สาธารณะแบบย่อ

การใช้งาน

อินเทอร์เฟซความช่วยเหลือของ Buf ให้ข้อมูลสรุปสำหรับคำสั่งและแฟล็ก:

buf --help

หากต้องการข้อมูลการใช้งานที่ครอบคลุมมากขึ้น โปรดดูเอกสารประกอบของ Buf โดยเฉพาะคำแนะนำเหล่านี้:

• buf breaking
• buf build
• buf generate
• buf lint
• buf format
• buf registry (สำหรับการใช้ BSR)

CLI ทำลายนโยบายการเปลี่ยนแปลง

เราจะไม่ทำการเปลี่ยนแปลงที่สำคัญภายใน CLI เวอร์ชันหลักที่กำหนด หลังจาก buf มาถึงเวอร์ชัน 1.0 คุณจะคาดว่าจะไม่มีการเปลี่ยนแปลงใด ๆ จนกว่าจะถึงเวอร์ชัน 2.0 แต่เนื่องจากเราไม่มีแผนที่จะออกเวอร์ชัน 2.0 เราจึงไม่น่าจะทำลาย CLI buf

นโยบายการเปลี่ยนแปลงที่ทำลายล้างนี้ใช้ ไม่ ได้กับคำสั่งที่อยู่ด้านหลัง buf beta gate และคุณควรคาดหวังว่าจะทำลายการเปลี่ยนแปลงคำสั่งต่างๆ เช่น buf beta registry อย่างไรก็ตาม นโยบายจะมีผลบังคับใช้เมื่อคำสั่งหรือแฟล็กเหล่านั้นถูกยกระดับออกจากรุ่นเบต้า

เป้าหมายของเราสำหรับ Protobuf

เป้าหมายของ Buf คือการแทนที่กระบวนทัศน์ปัจจุบันของการพัฒนา API ซึ่งมีศูนย์กลางอยู่ที่ REST/JSON ด้วยกระบวนทัศน์ ที่ขับเคลื่อนด้วยสคีมา การกำหนด API โดยใช้ IDL ให้ประโยชน์มากมายเหนือ REST/JSON และ Protobuf นั้นเป็น IDL ที่เสถียรและนำไปใช้อย่างกว้างขวางที่สุดในอุตสาหกรรม เราเลือกที่จะสร้างบนรากฐานที่เชื่อถือได้อย่างกว้างขวางนี้ แทนที่จะสร้าง IDL ใหม่ตั้งแต่เริ่มต้น

แต่ถึงแม้จะมีข้อดีทางเทคนิค แต่ การใช้ Protobuf จริงๆ ก็มีความท้าทายมากกว่าที่ควรจะเป็นมานานแล้ว Buf CLI และ BSR เป็นรากฐานสำคัญของความพยายามของเราในการเปลี่ยนแปลงสิ่งนั้นไปในทางที่ดี และทำให้ Protobuf เชื่อถือได้และใช้งานง่ายสำหรับเจ้าของบริการและลูกค้า กล่าวคือ เพื่อสร้าง ระบบนิเวศ Protobuf ที่ทันสมัย

แม้ว่าเราตั้งใจที่จะปรับปรุง buf CLI และ BSR ทีละน้อย แต่เรามั่นใจว่ารากฐานพื้นฐานสำหรับระบบนิเวศดังกล่าวได้เกิดขึ้น แล้ว

รีจิสทรี Buf Schema

Buf Schema Registry (BSR) เป็นแพลตฟอร์ม SaaS สำหรับจัดการ Protobuf API ของคุณ โดยให้การลงทะเบียนแบบรวมศูนย์และแหล่งข้อมูลเดียวสำหรับเนื้อหา Protobuf ทั้งหมดของคุณ ซึ่งรวมถึงไม่เพียงแค่ไฟล์ .proto ของคุณเท่านั้น แต่ยังรวมถึงปลั๊กอินระยะไกลด้วย แม้ว่า BSR จะมี UI เบราว์เซอร์ที่ใช้งานง่าย แต่ buf ช่วยให้คุณสามารถทำงานที่เกี่ยวข้องกับ BSR ส่วนใหญ่ได้จากบรรทัดคำสั่ง เช่น การพุชซอร์ส Protobuf ไปยังรีจิสทรี และการจัดการผู้ใช้และที่เก็บข้อมูล

BSR ไม่จำเป็นต้องใช้ buf เราได้ทำให้คุณสมบัติหลักของ buf CLI พร้อมใช้งานสำหรับผู้ใช้ Protobuf ทุกคน

คุณสมบัติ CLI ขั้นสูงเพิ่มเติม

แม้ว่าคุณสมบัติหลักของ buf ควรครอบคลุมกรณีการใช้งานส่วนใหญ่ เราได้รวมคุณสมบัติขั้นสูงเพิ่มเติมบางส่วนไว้เพื่อครอบคลุมกรณีขอบ:

• การค้นพบไฟล์อัตโนมัติ Buf เดินแผนผังไฟล์ของคุณและสร้างไฟล์ .proto ตามการกำหนดค่าบิลด์ที่คุณให้มา ซึ่งหมายความว่าคุณไม่จำเป็นต้องระบุ --proto_paths ด้วยตนเองอีกต่อไป อย่างไรก็ตาม คุณยังคงสามารถระบุไฟล์ .proto ได้ด้วยตนเองผ่านแฟล็ก CLI ในกรณีที่จำเป็นต้องปิดใช้งานการค้นหาไฟล์
• การกำหนดค่ากฎแบบละเอียด สำหรับ Linting และการทำลายการเปลี่ยนแปลง แม้ว่าเราจะมีค่าเริ่มต้นที่แนะนำ แต่คุณสามารถเลือกชุดกฎที่กรณีการใช้งานของคุณต้องการได้เสมอ โดยมีกฎ Lint 40 ข้อและกฎการเปลี่ยนแปลงที่แตกหัก 53 ข้อ
• รูปแบบข้อผิดพลาดที่กำหนดค่าได้ สำหรับเอาต์พุต CLI buf ส่งออกข้อมูลใน file:line:column:message ตามค่าเริ่มต้นสำหรับข้อผิดพลาด lint แต่ละรายการและการเปลี่ยนแปลงที่พบเจอ แต่คุณยังสามารถเลือกเอาต์พุต JSON, MSVS, JUnit และ Github Actions ได้ด้วย
• การรวมตัวแก้ไข ขับเคลื่อนโดยเอาต์พุตข้อผิดพลาดแบบละเอียดของ buf ขณะนี้เราจัดให้มีการผสานรวม Linting สำหรับทั้ง Vim และ Visual Studio Code และ JetBrains IDE เช่น IntelliJ และ GoLand แต่เราวางแผนที่จะสนับสนุนโปรแกรมแก้ไขอื่น ๆ เช่น Emacs ในอนาคต
• การกำหนดเป้าหมายอินพุตสากล Buf ช่วยให้คุณสามารถดำเนินการต่างๆ เช่น Linting และการทำลายการตรวจจับการเปลี่ยนแปลง ไม่เพียงแต่กับไฟล์ .proto ในเครื่องเท่านั้น แต่ยังรวมถึงอินพุตอื่นๆ ที่หลากหลาย เช่น tarball และไฟล์ ZIP, พื้นที่เก็บข้อมูล Git ระยะไกล และไฟล์รูปภาพที่สร้างไว้ล่วงหน้า
• ความเร็ว . คอมไพเลอร์ Protobuf ภายในของ Buf รวบรวมแหล่งที่มา Protobuf ของคุณโดยใช้คอร์ที่มีอยู่ทั้งหมดโดยไม่กระทบต่อเอาต์พุตที่กำหนด ซึ่งเร็วกว่า protoc มาก ซึ่งช่วยให้ได้รับความคิดเห็นแทบจะในทันที ซึ่งมีความสำคัญเป็นพิเศษสำหรับฟีเจอร์ต่างๆ เช่น การรวมตัวแก้ไข

ขั้นตอนต่อไป

เมื่อคุณติดตั้ง buf แล้ว เราขอแนะนำให้ทำตามบทช่วยสอน CLI ซึ่งให้ภาพรวมกว้างๆ แต่ใช้งานได้จริงเกี่ยวกับฟังก์ชันหลักของ CLI ทัวร์ใช้เวลาประมาณ 10 นาทีจึงจะเสร็จสิ้น

หลังจากเสร็จสิ้นการทัวร์ชมแล้ว ให้ตรวจสอบเอกสารส่วนที่เหลือเกี่ยวกับเรื่องที่คุณสนใจ

ชุมชน

หากต้องการความช่วยเหลือและการสนทนาเกี่ยวกับ Protobuf แนวปฏิบัติที่ดีที่สุด และอื่นๆ อีกมากมาย เข้าร่วมกับเราที่ Slack

สำหรับการอัปเดตเกี่ยวกับ Buf CLI ให้ติดตาม repo นี้บน GitHub

สำหรับคำขอคุณลักษณะ ข้อบกพร่อง หรือคำถามทางเทคนิค โปรดส่งอีเมลถึงเราที่ [email protected] หากต้องการสอบถามข้อมูลทั่วไปหรือรวมไว้ในฟีเจอร์เบต้าที่กำลังจะมีขึ้น โปรดส่งอีเมลถึงเราที่ [email protected]