Buf CLI

Buf

Buf は Protobuf の最新ツールチェーンです。日常的な protoc の使用を、実行速度の速いコンパイラー、モジュールを認識するワークスペース、フォーマット、リンティング、破壊的変更の検出、コード生成、依存関係管理、API 呼び出し、そして Buf Schema Registry 用のクライアントに置き換えます。

今も protoc -I ... を使ったシェルスクリプトで Protobuf を扱っているなら、Buf が望んでいるアップグレードです。同じスキーマ言語、同じ生成コードプラグインの仕組みを維持しながら、複雑な要素を減らし、ローカルの .proto ファイルから、管理されたバージョン付き API へ直接つなげます。

はじめに

Homebrew で buf をインストールします。

brew install bufbuild/buf/buf

ワークスペースを初期化し、すべての Protobuf リポジトリが通過すべきチェックを実行します。

buf config init
buf build
buf format -w
buf lint
buf breaking --against '.git#branch=main'

手作業で管理するシェルコマンドの代わりに、リポジトリにチェックインされた buf.gen.yaml からコードを生成します。

buf generate

空のワークスペースから稼働する Connect サービスまでを順に説明するチュートリアルは、Buf CLI のクイックスタートを実行してください。

Buf が選ばれる理由

Protobuf の作業	protoc とスクリプトを使う場合	Buf を使う場合
ファイルの検索	-I パスを管理し、インポート順が動作に影響しないことを願います。	buf.yaml でモジュールを一度宣言すれば、Buf がファイルを検出し、あいまいなインポートを拒否します。
コンパイル	ローカルの protoc のインストールを管理し、変化する stderr 出力を解析します。	protoc のディスクリプター出力に照らしてテストされ、再現性のある並列コンパイル向けに構築された Buf 内蔵コンパイラーを使います。
スタイル	レビューコメントや別のツールに頼ります。	40 個以上の組み込みルールとカスタムプラグインを使って、ローカル、エディター、CI、BSR で buf lint を実行します。
互換性	生成コードやクライアントが失敗したり、シリアライズされたデータが読み取れなくなったりしてから、問題を見つけます。	マージ前に、Git、BSR モジュール、tarball、zip ファイル、Buf イメージを対象に buf breaking を実行します。
コード生成	すべてのマシンにプラグインのバイナリをインストールし、長いコマンドに動作を記述します。	プラグイン、出力先、オプション、入力、マネージドモードの設定を buf.gen.yaml に記述し、ローカルまたはリモートのプラグインを使います。
依存関係	.proto ファイルをリポジトリ間でコピーするか、手作業でベンダリングします。	buf.yaml で BSR モジュールの依存関係を宣言し、buf.lock でバージョンを固定します。
API 利用者	スキーマとコード生成の手順を共有します。	BSR に公開し、利用者が go get、npm install、Maven、Gradle、pip install、NuGet、Cargo、SwiftPM、CMake、またはアーカイブを使って生成済み SDK をインストールできるようにします。
ガバナンス	すべてのリポジトリでチェックを作り直し、各チームが有効な状態を保つことを願います。	BSR のレイヤーで、破壊的変更、名前の一意性、カスタムポリシーを適用します。

主要な CLI 機能は BSR アカウントなしで動作します。レジストリにサインインすると、必要に応じて配布、リモートプラグイン、生成済み SDK、ホスト型ドキュメント、プライベートモジュールの依存関係解決、サーバー側のチェックを利用できます。

コアワークフロー

Buf は .proto ファイルのディレクトリツリーをモジュールとして扱い、プロジェクトをワークスペースとして扱います。小さな buf.yaml を用意するだけで、ビルド、リンティング、破壊的変更の検出、コード生成、依存関係の解決、公開で同じ入力を使用できます。

version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

そこから使うコマンドは、意図的にシンプルになっています。

buf build
buf format -w
buf lint
buf breaking --against '.git#branch=main'
buf generate
buf push

buf build はワークスペースをコンパイルします。buf lint は、作成者がまだ編集中の段階で API の構造上の問題を検出します。buf breaking は現在のスキーマを以前のバージョンと比較し、ソース、JSON、ワイヤ形式の互換性に関する問題を報告します。buf generate は、チェックインされたテンプレートから protoc プラグインを実行します。buf push は、名前付きモジュールを BSR に公開します。

コード生成

buf generate は通常の protoc プラグインモデルと互換性がありますが、コード生成の設定をバージョン管理された設定に移します。この例では、BSR でホストされるリモートプラグインを使い、proto/ から Go Protobuf 型と ConnectRPC ハンドラーを生成します。

version: v2
clean: true
managed:
  enabled: true
  override:
    - file_option: go_package_prefix
      value: github.com/acme/weather/gen/go
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/connectrpc/go
    out: gen/go
    opt: paths=source_relative
inputs:
  - directory: proto

リモートプラグインを使えば、開発者の各マシンや CI ランナーにジェネレーターのバイナリをインストールして保守する必要がなくなります。マネージドモードを使うと、API の提供者は言語固有のファイルオプションを .proto ファイルから除外しつつ、利用者は対象言語に適した正しい生成パッケージ名を取得できます。

ローカルプラグインも使用できます。プラグインが標準の Protobuf プラグインプロトコルに対応していれば、Buf で実行できます。

破壊的変更

Protobuf の互換性は単一のものではありません。フィールドの名前を変更すると、バイナリワイヤ形式との互換性は保たれたまま、生成されたソースコードとの互換性が損なわれることがあります。一方、フィールドを int32 から string に変更すると、既存のシリアライズ済みメッセージがすべて影響を受けます。buf breaking は、FILE、PACKAGE、WIRE_JSON、WIRE の互換性ルールカテゴリによって、この違いを明確にします。

buf breaking --against '.git#branch=main'

--against には、Git ブランチ、BSR モジュール、tarball、zip ファイル、ローカルディレクトリ、またはビルド済み Buf イメージを指定できます。実際のリポジトリでは、この点が重要です。同じコマンドを開発者のマシン、CI、リリース自動化で使用できます。

Buf Schema Registry

Buf Schema Registry は Protobuf 対応のレジストリです。モジュールを保存し、コンパイルを検証し、ドキュメントを生成し、依存関係を解決し、リモートプラグインをホストし、生成済み SDK を提供します。また、破壊的変更が利用者に届く前にスキーマチェックを適用できます。

buf push

モジュールを BSR にプッシュすると、組織の Protobuf API の信頼できる情報源になります。利用者は BSR モジュールとしてスキーマに依存したり、通常のパッケージマネージャーから生成済み SDK をインストールしたり、BSR のドキュメントでサービス、メッセージ、フィールド、列挙型、参照、過去のコミットを確認したりできます。

関連プロジェクト

スキーマをコード生成以外にも活用すると、Buf の有用性が高まります。ConnectRPC は Protobuf スキーマを使って、サービス定義を分けることなく Connect、gRPC、gRPC-Web に対応するシンプルな HTTP API を構築します。Protobuf-ES は、JavaScript と TypeScript のユーザーに最新の Protobuf ランタイムとジェネレーターを提供します。Protovalidate はスキーマに検証ルールを定義し、複数の言語で一貫して実行します。

1 つのコントラクトでワークフロー全体、つまりコンパイル、リンティング、互換性チェック、生成されたクライアントとサーバー、検証、API 呼び出し、パッケージ公開、管理された変更を駆動できます。

インストール

Homebrew を使うと、buf、protoc-gen-buf-breaking、protoc-gen-buf-lint のバイナリに加えて、Bash、Fish、PowerShell、zsh 用のシェル補完スクリプトをインストールできます。

brew install bufbuild/buf/buf

その他の対応しているインストール方法には、npm、Windows、Docker、バイナリのダウンロード、tarball、ソースからのビルド、minisign による検証があります。すべての方法については、インストールのドキュメントを参照してください。

CLI の安定性

Buf CLI のリリースでは、メジャーバージョン内で破壊的変更は行われません。buf は v1.0 に達しているため、v2.0 までは破壊的変更がないと見込めます。v2.0 をリリースする予定はありません。

このポリシーは、buf beta ゲートの背後にあるコマンドには適用されません。ベータコマンドが正式に昇格するまでは、破壊的変更が行われる可能性があります。

ドキュメント

• Buf CLI
• CLI クイックスタート
• モジュールとワークスペース
• コード生成
• Lint
• 破壊的変更の検出
• フォーマット
• buf curl による API の呼び出し
• Buf Schema Registry
• 生成された SDK
• リモートプラグイン
• スキーマチェック
• protoc からの移行

コミュニティ

Protobuf、ベストプラクティス、Buf に関するサポートや議論については、Slack にご参加ください。

バグ、機能リクエスト、技術的な質問については、このリポジトリで Issue を作成するか、[email protected] にメールでお問い合わせください。一般的なお問い合わせは、[email protected] にメールでご連絡ください。