この記事について

Protocol Buffers用 Go言語API に新しく V2 (APIv2) が出たことにより、import のパス、リポジトリ、protoc-gen-go などに違いがあり混乱したので整理してみた。

[2021/2/13更新]
初回投稿時点(2020/05/11)では APIv2 用の protoc-gen-go-grpc がリリースされてませんでしたが、2020年10月にリリースされたため内容を更新しました。

Protocol Buffers用 Go言語API について

Protocol Buffers(以下、protobuf)は言語ニュートラルなデータのシリアライズの仕組みで、Go言語でも protobuf を使うための API が提供されている。

最初の API が提供されたのが 2010年ごろで、これを APIv1 と呼ぶ。
そして、2020年3月に新しい APIv2 がリリースされた。

APIv2 についてのごく簡単な特徴：

*.proto ファイルで定義された protobuf のアノテーションを Go から読めるようにした
APIv2 は後方互換性はない
- APIv1 は今後もずっとサポートを継続する(原文: We intend to maintain support for APIv1 indefinitely.)

[補足] protoc-gen-go について
*.proto ファイルのコンパイルには protoc というコンパイラを用いるが、protobuf 自体は言語ニュートラルなためGo言語用のコードの生成するには protoc-gen-go というプラグインが必要になる。この protoc-gen-go と後述する gRPC のスタブコード生成にも APIv1 と APIv2 で違いが生じている。

APIv1 と APIv2 の違い

APIv1

最新バージョンは v1.4 系
- v1.4.0 から内部的には APIv2 を使って実装されている
APIv1 の import パス等は以下を参照

対象	値
import のパス	github.com/golang/protobuf
ソースのリポジトリ	https://github.com/golang/protobuf
protoc-gen-go	github.com/golang/protobuf/protoc-gen-go
gRPCスタブコード生成	同上

APIv2

バージョンは v1.20.0 から始まる
- APIv1 のバージョンが 1.20 まで進まないだろうという予想とのこと
APIv2 の import パス等は以下を参照

対象	値
import のパス	google.golang.org/protobuf
ソースのリポジトリ	https://github.com/protocolbuffers/protobuf-go
protoc-gen-go	google.golang.org/protobuf/cmd/protoc-gen-go
gRPCスタブコード生成	google.golang.org/grpc/cmd/protoc-gen-go-grpc

protoc-gen-go と gRPC のスタブコード生成について

APIv1 の場合

APIv1 では protoc に --go_out=plugins=grpc オプションを付けることで、protoc-gen-go に gRPC スタブコードを生成させることができた。

gRPC用スタブコードの生成例

protoc --go_out=plugins=grpc:. sample.proto

APIv2 の場合

APIv2 の protoc-gen-go 自体は gRPC のスタブコードを生成しなくなり、追加で protoc-gen-go-grpc というプラグインが必要になった。

プラグインのインストール例

export GO111MODULE=on
go get google.golang.org/protobuf/cmd/protoc-gen-go
go get google.golang.org/grpc/cmd/protoc-gen-go-grpc