本記事はBuf CLIの使い方 1回目です
概要
本記事ではBuf CLIのチュートリアルを通して使い方を理解していきたいと思います。
Buf CLI
Buf CLIはProtobufスキーマの管理に役立つツールです。コード生成、変更検出、リンティング、書式設定などさまざまな機能を提供し、Protobufの開発と保守を支援します。お好みのプラグインや言語で動作し、Buf Schema Registryにある認定プラグインの膨大なライブラリにアクセスできます。
参照: https://buf.build/docs/cli/
Buf CLIのインストール
Homebrewを使用してインストールできます
brew install bufbuild/buf/buf
このインストールには以下も含まれます。
-
buf,protoc-gen-buf-breaking,protoc-gen-buf-lintのバイナリ -
bufの Bash 補完 -
bufの Fish 補完 -
bufの Zsh 補完
参照: https://buf.build/docs/cli/installation/
正常にインストールできていれば以下のコマンドでバージョンを確認できます。
buf --version
% buf --version
1.50.0
チュートリアル
buf-tourのリポジトリのクローン
以下のコマンドでbuf-tourをクローンします
git clone git@github.com:bufbuild/buf-tour.git
GitHub CLI ghをインストールしている場合は以下でも大丈夫です。
gh repo clone bufbuild/buf-tour
このリポジトリは start ディレクトリと finish ディレクトリがあり、start ディレクトリでファイルを操作して、最終的に finish ディレクトリの状態に一致します。
今回は start/getting-started-with-buf-cli を使用するのでワーキングディレクトリを変更します。
cd buf-tour/start/getting-started-with-buf-cli
ワークスペースの構成
設定の初期化を実施します。
buf config init
以下のようなbuf.yamlが生成されます。
# For details on buf.yaml configuration, visit https://buf.build/docs/configuration/v2/buf-yaml
version: v2
lint:
use:
- STANDARD
breaking:
use:
- FILE
buf.yamlファイルはワークスペースのルートに置かれ、このファイルが定義するワークスペースは、すべてのBuf操作のデフォルト入力となります。
ディレクトリパスの更新とモジュールのビルド
生成された buf.yaml ファイルは、カレントディレクトリにパスが設定された1つのモジュールを持つワークスペースのように振る舞います。ワークスペース内のモジュールを明示的に定義するには、.proto ファイルを含むディレクトリのパスを指定します。
modules キーを使用して、buf.yaml ファイルに proto ディレクトリを追加します。
version: v2
modules:
- path: proto
lint:
use:
- STANDARD
breaking:
use:
- FILE
続行する前に、すべてが正しくセットアップされ、モジュールがビルドされることを確認してください。エラーがなければ、Bufモジュールは正しくセットアップされています。
buf build
コードの生成
モジュールの設定が終わったので、次はローカルコード生成を設定するための buf.gen.yaml ファイルを作成します。
buf.gen.yaml ファイルは、buf generate コマンドが与えられたモジュール上でどのように protoc プラグインを実行するかを制御します。
このファイルを使って、各protocプラグインが結果を書き込む場所を設定したり、各プラグインのオプションを指定したりできます。
カレントディレクトリに以下の内容のファイルを作成します。
version: v2
managed:
enabled: true
override:
- file_option: go_package_prefix
value: github.com/bufbuild/buf-tour/gen
plugins:
- remote: buf.build/protocolbuffers/go
out: gen
opt: paths=source_relative
- remote: buf.build/connectrpc/go
out: gen
opt: paths=source_relative
inputs:
- directory: proto
buf.gen.yamlファイルが設定できたので、PetStoreService APIに関連するConnect RPCとGoコードを生成できます。
以下のコマンドを実行します。
buf generate
生成が成功したら、 gen ディレクトリとその中に幾つかのファイルが作成されます。
getting-started-with-buf-cli
├── buf.gen.yaml
├── buf.yaml
├── gen
│ ├── google
│ │ └── type
│ │ └── datetime.pb.go
│ └── pet
│ └── v1
│ ├── pet.pb.go
│ └── petv1connect
│ └── pet.connect.go
└── proto
├── google
│ └── type
│ └── datetime.proto
└── pet
└── v1
└── pet.proto
ここまでで上記のような構成になっているはずです。
今回はここまでとします。