buf

Penggemar

CLI buf adalah alat terbaik untuk bekerja dengan Protocol Buffer. Ini menyediakan:

• Sebuah linter yang menerapkan pilihan dan struktur desain API yang baik.
• Detektor perubahan yang melanggar yang menerapkan kompatibilitas pada kode sumber atau tingkat kabel.
• Generator yang memanggil plugin Anda berdasarkan templat yang dapat dikonfigurasi.
• Pemformat yang memformat file Protobuf Anda sesuai dengan standar industri.
• Integrasi dengan Buf Schema Registry, termasuk manajemen ketergantungan penuh.

Instalasi

minuman rumahan

Anda dapat menginstal buf menggunakan Homebrew (macOS atau Linux):

brew install bufbuild/buf/buf

Ini menginstal:

• Biner buf , protoc-gen-buf-breaking , dan protoc-gen-buf-lint
• Skrip penyelesaian shell untuk Bash, Fish, Powershell, dan zsh

Metode lain

Untuk metode instalasi lainnya, lihat dokumentasi resmi kami, yang mencakup:

• Menginstal buf melalui npm
• Menginstal buf di Windows
• Menggunakan buf sebagai gambar Docker
• Menginstal sebagai biner, dari tarball, dan dari sumber melalui Rilis GitHub
• Memverifikasi rilis menggunakan kunci publik minisign

Penggunaan

Antarmuka bantuan Buf menyediakan ringkasan untuk perintah dan tanda:

buf --help

Untuk informasi penggunaan yang lebih komprehensif, lihat dokumentasi Buf, terutama panduan berikut:

• buf breaking
• buf build
• buf generate
• buf lint
• buf format
• buf registry (untuk menggunakan BSR)

CLI melanggar kebijakan perubahan

Kami tidak akan pernah membuat perubahan yang dapat menyebabkan gangguan pada versi utama CLI tertentu. Setelah buf mencapai v1.0, Anda tidak akan mengalami perubahan apa pun hingga v2.0. Namun karena kami tidak memiliki rencana untuk merilis v2.0, kemungkinan besar kami tidak akan pernah merusak CLI buf tersebut.

Kebijakan perubahan yang melanggar ini tidak berlaku untuk perintah di belakang gerbang buf beta , dan Anda akan mengharapkan perubahan yang dapat melanggar pada perintah seperti buf beta registry . Namun, kebijakan ini akan berlaku ketika perintah atau tanda tersebut dinaikkan dari versi beta.

Tujuan kami untuk Protobuf

Tujuan Buf adalah menggantikan paradigma pengembangan API saat ini, yang berpusat pada REST/JSON, dengan paradigma berbasis skema . Mendefinisikan API menggunakan IDL memberikan banyak keuntungan dibandingkan REST/JSON, dan Protobuf sejauh ini merupakan IDL yang paling stabil dan banyak diadopsi di industri. Kami memilih untuk membangun fondasi yang dipercaya secara luas ini daripada membuat IDL baru dari awal.

Namun terlepas dari kelebihan teknisnya, penggunaan Protobuf sebenarnya lebih menantang dari yang seharusnya. Buf CLI dan BSR adalah landasan upaya kami untuk mengubahnya demi kebaikan dan menjadikan Protobuf andal serta mudah digunakan bagi pemilik layanan dan klien—dengan kata lain, untuk menciptakan ekosistem Protobuf modern .

Meskipun kami bermaksud untuk meningkatkan CLI dan BSR secara buf , kami yakin bahwa landasan dasar untuk ekosistem tersebut sudah ada.

Registri Skema Buf

Buf Schema Registry (BSR) adalah platform SaaS untuk mengelola API Protobuf Anda. Ini menyediakan registri terpusat dan satu sumber kebenaran untuk semua aset Protobuf Anda, termasuk tidak hanya file .proto tetapi juga plugin jarak jauh. Meskipun BSR menyediakan UI browser yang intuitif, buf memungkinkan Anda melakukan sebagian besar tugas terkait BSR dari baris perintah, seperti memasukkan sumber Protobuf ke registri dan mengelola pengguna dan repositori.

BSR tidak diharuskan menggunakan buf . Kami telah membuat fitur inti buf CLI tersedia untuk semua pengguna Protobuf.

Fitur CLI yang lebih canggih

Meskipun fitur inti buf harus mencakup sebagian besar kasus penggunaan, kami telah menyertakan beberapa fitur lanjutan untuk mencakup kasus tepi:

• Penemuan file otomatis . Buf menelusuri pohon file Anda dan membuat file .proto sesuai dengan konfigurasi build yang Anda berikan, yang berarti Anda tidak perlu lagi menentukan --proto_paths secara manual. Namun, Anda masih dapat menentukan file .proto secara manual melalui tanda CLI jika penemuan file perlu dinonaktifkan.
• Konfigurasi aturan yang terperinci untuk perubahan linting dan gangguan. Meskipun kami memiliki rekomendasi default, Anda selalu dapat memilih kumpulan aturan persis yang diperlukan oleh kasus penggunaan Anda, dengan 40 aturan lint dan 53 aturan perubahan yang melanggar tersedia.
• Format kesalahan yang dapat dikonfigurasi untuk keluaran CLI. buf mengeluarkan informasi dalam file:line:column:message secara default untuk setiap kesalahan lint dan perubahan yang dapat menyebabkan gangguan, namun Anda juga dapat memilih keluaran Tindakan JSON, MSVS, JUnit, dan Github.
• Integrasi editor didorong oleh keluaran kesalahan granular buf . Saat ini kami menyediakan integrasi linting untuk Vim dan Visual Studio Code serta IDE JetBrains seperti IntelliJ dan GoLand, namun kami berencana untuk mendukung editor lain seperti Emacs di masa mendatang.
• Penargetan Masukan Universal . Buf memungkinkan Anda melakukan tindakan seperti linting dan menghentikan deteksi perubahan tidak hanya terhadap file .proto lokal tetapi juga terhadap berbagai Input lainnya, seperti file tarball dan ZIP, repositori Git jarak jauh, dan file gambar yang sudah dibuat sebelumnya.
• Kecepatan . Kompiler Protobuf internal Buf mengkompilasi sumber Protobuf Anda menggunakan semua inti yang tersedia tanpa mengorbankan keluaran deterministik, yang jauh lebih cepat daripada protoc . Hal ini memungkinkan umpan balik yang hampir seketika, yang sangat penting untuk fitur seperti integrasi editor.

Langkah selanjutnya

Setelah Anda menginstal buf , kami sarankan untuk menyelesaikan tutorial CLI, yang memberikan gambaran luas namun langsung mengenai fungsi inti CLI. Tur ini memakan waktu sekitar 10 menit untuk diselesaikan.

Setelah menyelesaikan tur, periksa dokumen lainnya untuk bidang minat spesifik Anda.

Masyarakat

Untuk bantuan dan diskusi seputar Protobuf, praktik terbaik, dan banyak lagi, bergabunglah dengan kami di Slack.

Untuk pembaruan pada Buf CLI, ikuti repo ini di GitHub.

Untuk permintaan fitur, bug, atau pertanyaan teknis, kirim email kepada kami di [email protected]. Untuk pertanyaan umum atau penyertaan dalam fitur beta kami yang akan datang, kirimkan email kepada kami di [email protected].