buf

バフ

buf CLI は、プロトコル バッファーを操作するための最適なツールです。それは以下を提供します:

• 適切な API 設計の選択と構造を強制するリンター。
• ソース コードまたはワイヤ レベルで互換性を強制する重大な変更検出器。
• 構成可能なテンプレートに基づいてプラグインを呼び出すジェネレーター。
• 業界標準に従って Protobuf ファイルをフォーマットするフォーマッタ。
• 完全な依存関係管理を含む、Buf Schema Registry との統合。

インストール

自作

Homebrew (macOS または Linux) を使用してbufインストールできます。

brew install bufbuild/buf/buf

これにより以下がインストールされます。

• buf 、 protoc-gen-buf-breaking 、およびprotoc-gen-buf-lintバイナリ
• Bash、Fish、Powershell、zsh のシェル補完スクリプト

その他の方法

他のインストール方法については、以下について説明している公式ドキュメントを参照してください。

• npm経由でbufインストールする
• Windows へのbufのインストール
• buf Docker イメージとして使用する
• バイナリとして、tarball から、および GitHub リリースを介したソースからインストールする
• ミニサイン公開キーを使用したリリースの検証

使用法

Buf のヘルプ インターフェイスには、コマンドとフラグの概要が表示されます。

buf --help

より包括的な使用法情報については、Buf のドキュメント、特に次のガイドを参照してください。

• buf breaking
• buf build
• buf generate
• buf lint
• buf format
• buf registry (BSR を使用するため)

CLI 重大な変更ポリシー

CLI の特定のメジャー バージョン内で重大な変更を行うことはありません。 buf v1.0 に達した後は、v2.0 まで重大な変更は期待できません。しかし、v2.0 をリリースする予定はないため、 buf CLI を壊すことはおそらくないでしょう。

この重大な変更ポリシーは、 buf betaゲートの背後にあるコマンドには適用されません。また、 buf beta registryなどのコマンドには重大な変更が適用されることが予想されます。ただし、これらのコマンドまたはフラグがベータ版から昇格されると、ポリシーは有効になります。

Protobuf の目標

Buf の目標は、REST/JSON を中心とした API 開発の現在のパラダイムをスキーマ駆動のパラダイムに置き換えることです。 IDL を使用して API を定義すると、REST/JSON に比べて多くの利点が得られます。Protobuf は業界で最も安定しており、広く採用されている IDL です。私たちは、新しい IDL を最初から作成するのではなく、広く信頼されているこの基盤の上に構築することを選択しました。

しかし、その技術的な利点にもかかわらず、Protobuf を実際に使用することは長い間、必要以上に困難でした。 Buf CLI と BSR は、この状況を永久に変え、Protobuf をサービス所有者とクライアントの両方にとって信頼性が高く使いやすいものにする、つまり最新の Protobuf エコシステムを作成するという私たちの取り組みの基礎です。

私たちはbuf CLI と BSR を段階的に改善するつもりですが、このようなエコシステムの基本的な基盤はすでに整っていると確信しています。

Buf スキーマ レジストリ

Buf Schema Registry (BSR) は、Protobuf API を管理するための SaaS プラットフォームです。これは、 .protoファイルだけでなくリモート プラグインも含む、すべての Protobuf アセットに対して一元化されたレジストリと単一の信頼できる情報源を提供します。 BSR は直感的なブラウザ UI を提供しますが、 buf使用すると、Protobuf ソースのレジストリへのプッシュやユーザーとリポジトリの管理など、ほとんどの BSR 関連タスクをコマンド ラインから実行できます。

BSR はbuf使用する必要はありません。 buf CLI のコア機能をすべてのProtobuf ユーザーが利用できるようにしました。

より高度な CLI 機能

bufのコア機能はほとんどのユースケースをカバーする必要がありますが、エッジケースをカバーするためにいくつかのより高度な機能が組み込まれています。

• 自動ファイル検出。 Buf はファイル ツリーを調べ、指定されたビルド構成に従って.protoファイルをビルドします。つまり、 --proto_paths手動で指定する必要がなくなりました。ただし、ファイル検出を無効にする必要がある場合は、CLI フラグを使用して.protoファイルを手動で指定することもできます。
• lint および破壊的変更のためのきめ細かいルール設定。推奨されるデフォルトはありますが、40 個の lint ルールと 53 個の重大な変更ルールを使用して、ユースケースに必要な正確なルールのセットをいつでも選択できます。
• CLI 出力の構成可能なエラー形式。 buf 、デフォルトで、各 lint エラーおよび発生した重大な変更についてfile:line:column:message形式で情報を出力しますが、JSON、MSVS、JUnit、および Github Actions 出力を選択することもできます。
• bufの詳細なエラー出力によるエディターの統合。現在、Vim と Visual Studio Code の両方、および IntelliJ や GoLand などの JetBrains IDE の lint 統合を提供していますが、将来的には Emacs などの他のエディターもサポートする予定です。
• ユニバーサル入力ターゲティング。 Buf を使用すると、ローカルの.protoファイルだけでなく、tarball や ZIP ファイル、リモート Git リポジトリ、ビルド済みイメージ ファイルなどの他の幅広い入力に対しても、lint や重大な変更の検出などのアクションを実行できます。
• スピード。 Buf の内部 Protobuf コンパイラは、確定的な出力を損なうことなく、利用可能なすべてのコアを使用して Protobuf ソースをコンパイルします。これはprotocよりもかなり高速です。これにより、ほぼ瞬時のフィードバックが可能になります。これは、エディターの統合などの機能にとって特に重要です。

次のステップ

bufインストールしたら、CLI チュートリアルを完了することをお勧めします。このチュートリアルでは、CLI のコア機能の広範かつ実践的な概要が提供されます。ツアーの所要時間は約 10 分です。

ツアーが完了したら、興味のある特定の分野についてドキュメントの残りを確認してください。

コミュニティ

Protobuf に関するヘルプやディスカッション、ベスト プラクティスなどについては、Slack にご参加ください。

Buf CLI の更新については、GitHub のこのリポジトリをフォローしてください。

機能リクエスト、バグ、技術的な質問については、[email protected] まで電子メールでお問い合わせください。一般的なお問い合わせや、今後の機能ベータ版への参加については、[email protected] まで電子メールでお問い合わせください。