Go 生成コードガイド（Opaque）

protocol bufferコンパイラが、任意のプロトコル定義に対してどのようなGoコードを生成するかを正確に説明します。

proto2 と proto3 の生成コードの違いが強調されています。これらの違いはこのドキュメントで説明されている生成コードにあり、両バージョンで同じ基本APIにはないことに注意してください。このドキュメントを読む前に、proto2言語ガイドおよび/またはproto3言語ガイドを読む必要があります。

注意

現在表示しているのは、最新バージョンであるOpaque APIのドキュメントです。古いOpen Struct APIを使用する.protoファイル（対応する.protoファイルのAPIレベル設定で確認できます）を扱っている場合は、対応するドキュメントについてはGo生成コード（Open）を参照してください。Opaque APIの導入については、Go Protobuf: 新しいOpaque APIを参照してください。

コンパイラの呼び出し

プロトコルバッファコンパイラは、Goコードを生成するためにプラグインを必要とします。Go 1.16以降を使用して、次のコマンドを実行してインストールします。

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

これにより、`$GOBIN` に `protoc-gen-go` バイナリがインストールされます。インストール場所を変更するには `$GOBIN` 環境変数を設定します。プロトコルバッファコンパイラがそれを見つけるためには、`$PATH` に含まれている必要があります。

プロトコルバッファコンパイラは、`go_out` フラグを指定して呼び出されたときにGo出力を生成します。`go_out` フラグの引数は、コンパイラがGo出力を書き込むディレクトリです。コンパイラは、各 `.proto` ファイル入力に対して1つのソースファイルを生成します。出力ファイル名は、`.proto` 拡張子を `.pb.go` に置き換えることで作成されます。

生成された`.pb.go`ファイルが出力ディレクトリ内のどこに配置されるかは、コンパイラフラグによって異なります。いくつかの出力モードがあります。

`paths=import` フラグが指定されている場合、出力ファイルはGoパッケージのインポートパス（`.proto` ファイル内の `go_package` オプションによって提供されるものなど）にちなんで名付けられたディレクトリに配置されます。たとえば、Goインポートパスが `example.com/project/protos/fizz` である入力ファイル `protos/buzz.proto` は、`example.com/project/protos/fizz/buzz.pb.go` に出力ファイルが生成されます。`paths` フラグが指定されていない場合、これがデフォルトの出力モードです。
`module=$PREFIX` フラグが指定されている場合、出力ファイルはGoパッケージのインポートパス（`.proto` ファイル内の `go_package` オプションによって提供されるものなど）にちなんで名付けられたディレクトリに配置されますが、指定されたディレクトリプレフィックスが出力ファイル名から削除されます。たとえば、Goインポートパスが `example.com/project/protos/fizz` で、`module` プレフィックスとして `example.com/project` が指定された入力ファイル `protos/buzz.proto` は、`protos/fizz/buzz.pb.go` に出力ファイルが生成されます。モジュールパス外のGoパッケージを生成するとエラーになります。このモードは、生成されたファイルをGoモジュールに直接出力するのに便利です。
`paths=source_relative` フラグが指定されている場合、出力ファイルは入力ファイルと同じ相対ディレクトリに配置されます。たとえば、入力ファイル `protos/buzz.proto` は、`protos/buzz.pb.go` に出力ファイルが生成されます。

`protoc-gen-go` に固有のフラグは、`protoc` を呼び出す際に `go_opt` フラグを渡すことで提供されます。複数の `go_opt` フラグを渡すことができます。例えば、実行時に

protoc --proto_path=src --go_out=out --go_opt=paths=source_relative foo.proto bar/baz.proto

コンパイラは `src` ディレクトリ内の入力ファイル `foo.proto` と `bar/baz.proto` を読み込み、出力ファイル `foo.pb.go` と `bar/baz.pb.go` を `out` ディレクトリに書き込みます。コンパイラは必要に応じて入れ子になった出力サブディレクトリを自動的に作成しますが、出力ディレクトリ自体は作成しません。

パッケージ

Go コードを生成するためには、すべての `.proto` ファイル（生成される `.proto` ファイルが間接的に依存するものを含む）に対して Go パッケージのインポートパスが提供されている必要があります。Go インポートパスを指定する方法は 2 つあります。

`.proto` ファイル内で宣言する、または
`protoc` を呼び出す際にコマンドラインで宣言する。

`.proto` ファイル内の Go パッケージを `.proto` ファイル自体で一元的に識別し、`protoc` を呼び出す際に渡すフラグのセットを簡素化するために、`.proto` ファイル内で宣言することを推奨します。特定の `.proto` ファイルの Go インポートパスが `.proto` ファイル自体とコマンドラインの両方で提供されている場合、後者が前者よりも優先されます。

Go インポートパスは、Go パッケージの完全なインポートパスを持つ `go_package` オプションを宣言することによって、`.proto` ファイル内でローカルに指定されます。使用例：

option go_package = "example.com/project/protos/fizz";

コンパイラを呼び出す際に、1つ以上の `M${PROTO_FILE}=${GO_IMPORT_PATH}` フラグを渡すことで、Go のインポートパスをコマンドラインで指定できます。使用例：

protoc --proto_path=src \
  --go_opt=Mprotos/buzz.proto=example.com/project/protos/fizz \
  --go_opt=Mprotos/bar.proto=example.com/project/protos/foo \
  protos/buzz.proto protos/bar.proto

すべての `.proto` ファイルからその Go インポートパスへのマッピングはかなり大きくなる可能性があるため、この Go インポートパスを指定する方法は、通常、依存関係ツリー全体を制御する何らかのビルドツール（例: Bazel）によって実行されます。特定の `.proto` ファイルに対して重複するエントリがある場合、最後に指定されたものが優先されます。

`go_package` オプションと `M` フラグの両方について、値にはインポートパスとセミコロンで区切られた明示的なパッケージ名を含めることができます。例: `"example.com/protos/foo;package_name"`。パッケージ名はデフォルトでインポートパスから適切に派生するため、この使用方法は推奨されません。

インポートパスは、ある`.proto`ファイルが別の`.proto`ファイルをインポートするときに、どのようなインポートステートメントを生成する必要があるかを決定するために使用されます。たとえば、`a.proto`が`b.proto`をインポートする場合、生成された`a.pb.go`ファイルは、生成された`b.pb.go`ファイルを含むGoパッケージをインポートする必要があります（両方のファイルが同じパッケージにある場合を除く）。インポートパスは、出力ファイル名を構築するためにも使用されます。詳細については、上記の「コンパイラの呼び出し」セクションを参照してください。

Go のインポートパスと、`.proto` ファイル内の `package` 指定子との間には相関関係はありません。後者はプロトコルバッファの名前空間のみに関連し、前者は Go の名前空間のみに関連します。また、Go のインポートパスと `.proto` のインポートパスの間にも相関関係はありません。

APIレベル

生成されるコードは、Open Struct API または Opaque API のいずれかを使用します。導入については、Go Protobuf: The new Opaque API ブログ投稿を参照してください。

`.proto` ファイルが使用する構文に応じて、使用される API は次のとおりです。

`.proto` 構文	APIレベル
proto2	Open Struct API
proto3	Open Struct API
2023年版	Open Struct API
2024年以降の版	Opaque API

`.proto` ファイルで `api_level` エディション機能を設定することで API を選択できます。これはファイルごと、またはメッセージごとに設定できます。

edition = "2023";

package log;

import "google/protobuf/go_features.proto";
option features.(pb.go).api_level = API_OPAQUE;

message LogEntry { … }

便宜上、protocコマンドラインフラグでデフォルトのAPIレベルをオーバーライドすることもできます。

protoc […] --go_opt=default_api_level=API_HYBRID

特定のファイルに対して（すべてのファイルではなく）デフォルトのAPIレベルを上書きするには、`apilevelM` マッピングフラグ（インポートパスの `M` フラグと同様）を使用します。

protoc […] --go_opt=apilevelMhello.proto=API_HYBRID

コマンドラインフラグは、まだproto2またはproto3構文を使用している.protoファイルでも機能しますが、.protoファイル内からAPIレベルを選択したい場合は、まずそのファイルをeditionsに移行する必要があります。

メッセージ

単純なメッセージ宣言を考えます。

message Artist {}

プロトコルバッファコンパイラは `Artist` という構造体を生成します。`*Artist` は `proto.Message` インターフェースを実装します。

`proto` パッケージは、バイナリ形式への変換やバイナリ形式からの変換を含む、メッセージを操作する機能を提供します。

`proto.Message` インターフェースは `ProtoReflect` メソッドを定義しています。このメソッドは、メッセージの`protoreflect.Message`を返します。これは、メッセージのリフレクションベースのビューを提供します。

`optimize_for` オプションは、Go コードジェネレータの出力には影響しません。

複数のゴルーチンが同じメッセージに並行してアクセスする場合、以下のルールが適用されます。

フィールドへの同時アクセス（読み取り）は安全ですが、1つ例外があります。
- 初めて遅延フィールドにアクセスすることは変更です。
同じメッセージ内の異なるフィールドを同時に変更することは安全です。
フィールドを同時に変更することは安全ではありません。
`proto` パッケージの関数（`proto.Marshal` や `proto.Size` など）と同時にメッセージを何らかの方法で変更することは安全ではありません。

ネストされた型

メッセージは別のメッセージ内で宣言できます。例：

message Artist {
  message Name {
  }
}

この場合、コンパイラは `Artist` と `Artist_Name` の2つの構造体を生成します。

フィールド

プロトコルバッファコンパイラは、メッセージ内で定義された各フィールドに対して、アクセサメソッド（セッターとゲッター）を生成します。

生成されたGoアクセサメソッドは、たとえ`.proto`ファイル内のフィールド名が小文字とアンダースコア（あるべきように）を使用している場合でも、常にキャメルケースの命名を使用することに注意してください。ケース変換は次のように機能します。

最初の文字はエクスポートのために大文字になります。最初の文字がアンダースコアの場合、それは削除され、大文字のXが前置されます。
内部のアンダースコアの後に小文字が続く場合、アンダースコアは削除され、続く文字は大文字になります。

したがって、Goでは `birth_year` フィールドに `GetBirthYear()` メソッドを使用してアクセスし、`_birth_year_2` フィールドに `GetXBirthYear_2()` メソッドを使用してアクセスできます。

単数フィールド

このフィールド定義について：

// proto2 and proto3
message Artist {
  optional int32 birth_year = 1;
}

// editions
message Artist {
  int32 birth_year = 1 [features.field_presence = EXPLICIT];
}

コンパイラは、以下のアクセサメソッドを持つGo構造体を生成します。

func (m *Artist) GetBirthYear() int32
func (m *Artist) SetBirthYear(v int32)

暗黙的な存在の場合、ゲッターは `birth_year` の `int32` 値、またはフィールドが設定されていない場合はその型のゼロ値（数値の場合は `0`、文字列の場合は空文字列）を返します。明示的な存在の場合、ゲッターは `birth_year` の `int32` 値、またはフィールドが設定されていない場合はデフォルト値を返します。デフォルトが明示的に設定されていない場合は、代わりにゼロ値が使用されます。

他のスカラーフィールド型（`bool`、`bytes`、`string`を含む）については、`int32` はスカラー値型テーブルに従って対応するGo型に置き換えられます。

明示的な存在を持つフィールドでは、これらのメソッドも使用できます。

func (m *Artist) HasBirthYear() bool
func (m *Artist) ClearBirthYear()

単数メッセージフィールド

メッセージ型を考えると：

message Band {}

`Band` フィールドを持つメッセージの場合

// proto2
message Concert {
  optional Band headliner = 1;
  // The generated code is the same result if required instead of optional.
}

// proto3 and editions
message Concert {
  Band headliner = 1;
}

コンパイラは、以下のアクセサメソッドを持つGo構造体を生成します。

type Concert struct { ... }

func (m *Concert) GetHeadliner() *Band { ... }
func (m *Concert) SetHeadliner(v *Band) { ... }
func (m *Concert) HasHeadliner() bool { ... }
func (m *Concert) ClearHeadliner() { ... }

`GetHeadliner()` アクセサメソッドは、`m` が nil であっても安全に呼び出すことができます。これにより、中間で `nil` チェックを行うことなく、get呼び出しを連結できます。

var m *Concert // defaults to nil
log.Infof("GetFoundingYear() = %d (no panic!)", m.GetHeadliner().GetFoundingYear())

フィールドが設定されていない場合、ゲッターはフィールドのデフォルト値を返します。メッセージの場合、デフォルト値はnilポインタです。

ゲッターとは対照的に、セッターはnilチェックを実行しません。したがって、nilである可能性のあるメッセージに対してセッターを安全に呼び出すことはできません。

繰り返しフィールド

繰り返しフィールドの場合、アクセサメソッドはスライス型を使用します。繰り返しフィールドを持つこのメッセージの場合

message Concert {
  // Best practice: use pluralized names for repeated fields:
  // /programming-guides/style#repeated-fields
  repeated Band support_acts = 1;
}

コンパイラは、以下のアクセサメソッドを持つGo構造体を生成します。

type Concert struct { ... }

func (m *Concert) GetSupportActs() []*Band { ... }
func (m *Concert) SetSupportActs(v []*Band) { ... }

同様に、`repeated bytes band_promo_images = 1;` というフィールド定義の場合、コンパイラは `[][]byte` 型を扱うアクセサを生成します。繰り返し列挙型 `repeated MusicGenre genres = 2;` の場合、コンパイラは `[]MusicGenre` 型を扱うアクセサを生成します。

次の例は、ビルダーを使用して `Concert` メッセージを構築する方法を示しています。

concert := Concert_builder{
  SupportActs: []*Band{
    {}, // First element.
    {}, // Second element.
  },
}.Build()

または、セッターを使用することもできます。

concert := &Concert{}
concert.SetSupportActs([]*Band{
    {}, // First element.
    {}, // Second element.
})

フィールドにアクセスするには、次のようにします。

support := concert.GetSupportActs() // support type is []*Band.
b1 := support[0] // b1 type is *Band, the first element in support_acts.

マップフィールド

各マップフィールドは、`map[TKey]TValue` 型を扱うアクセサを生成します。ここで、`TKey` はフィールドのキー型、`TValue` はフィールドの値型です。マップフィールドを持つこのメッセージの場合：

message MerchItem {}

message MerchBooth {
  // items maps from merchandise item name ("Signed T-Shirt") to
  // a MerchItem message with more details about the item.
  map<string, MerchItem> items = 1;
}

コンパイラは、以下のアクセサメソッドを持つGo構造体を生成します。

type MerchBooth struct { ... }

func (m *MerchBooth) GetItems() map[string]*MerchItem { ... }
func (m *MerchBooth) SetItems(v map[string]*MerchItem) { ... }

Oneof フィールド

oneof フィールドの場合、protobuf コンパイラは oneof 内の単一フィールドごとにアクセサを生成します。

oneof フィールドを持つこのメッセージの場合

package account;
message Profile {
  oneof avatar {
    string image_url = 1;
    bytes image_data = 2;
  }
}

コンパイラは、以下のアクセサメソッドを持つGo構造体を生成します。

type Profile struct { ... }

func (m *Profile) WhichAvatar() case_Profile_Avatar { ... }
func (m *Profile) GetImageUrl() string { ... }
func (m *Profile) GetImageData() []byte { ... }

func (m *Profile) SetImageUrl(v string) { ... }
func (m *Profile) SetImageData(v []byte) { ... }

func (m *Profile) HasAvatar() bool { ... }
func (m *Profile) HasImageUrl() bool { ... }
func (m *Profile) HasImageData() bool { ... }

func (m *Profile) ClearAvatar() { ... }
func (m *Profile) ClearImageUrl() { ... }
func (m *Profile) ClearImageData() { ... }

次の例は、ビルダーを使用してフィールドを設定する方法を示しています。

p1 := accountpb.Profile_builder{
  ImageUrl: proto.String("https://example.com/image.png"),
}.Build()

…または、同等に、セッターを使用する

// imageData is []byte
imageData := getImageData()
p2 := &accountpb.Profile{}
p2.SetImageData(imageData)

フィールドにアクセスするには、`WhichAvatar()` の結果に対して switch ステートメントを使用できます。

switch m.WhichAvatar() {
case accountpb.Profile_ImageUrl_case:
    // Load profile image based on URL
    // using m.GetImageUrl()

case accountpb.Profile_ImageData_case:
    // Load profile image based on bytes
    // using m.GetImageData()

case accountpb.Profile_Avatar_not_set_case:
    // The field is not set.

default:
    return fmt.Errorf("Profile.Avatar has an unexpected new oneof field %v", x)
}

ビルダー

ビルダーは、特に単体テストのようなネストされたメッセージを扱う場合に、単一の式でメッセージを構築および初期化するための便利な方法です。

他の言語（Javaなど）のビルダーとは異なり、Go protobufビルダーは関数間で渡されることを意図していません。代わりに、すぐに `Build()` を呼び出し、結果として得られるプロトメッセージを渡し、セッターを使用してフィールドを変更してください。

列挙型

次のような列挙型が与えられた場合：

message Venue {
  enum Kind {
    KIND_UNSPECIFIED = 0;
    KIND_CONCERT_HALL = 1;
    KIND_STADIUM = 2;
    KIND_BAR = 3;
    KIND_OPEN_AIR_FESTIVAL = 4;
  }
  Kind kind = 1;
  // ...
}

プロトコルバッファコンパイラは、その型を持つ型と一連の定数を生成します。

type Venue_Kind int32

const (
    Venue_KIND_UNSPECIFIED       Venue_Kind = 0
    Venue_KIND_CONCERT_HALL      Venue_Kind = 1
    Venue_KIND_STADIUM           Venue_Kind = 2
    Venue_KIND_BAR               Venue_Kind = 3
    Venue_KIND_OPEN_AIR_FESTIVAL Venue_Kind = 4
)

メッセージ内の列挙型（上記のような）の場合、型名はメッセージ名で始まります。

type Venue_Kind int32

パッケージレベルの列挙型の場合

enum Genre {
  GENRE_UNSPECIFIED = 0;
  GENRE_ROCK = 1;
  GENRE_INDIE = 2;
  GENRE_DRUM_AND_BASS = 3;
  // ...
}

Go 型名は proto 列挙型名から変更されません。

type Genre int32

この型は、与えられた値の名前を返す `String()` メソッドを持っています。

`Enum()` メソッドは、新しく割り当てられたメモリに指定された値を初期化し、対応するポインタを返します。

func (Genre) Enum() *Genre

プロトコルバッファコンパイラは、列挙型の各値に対して定数を生成します。メッセージ内の列挙型の場合、定数は囲むメッセージの名前で始まります。

const (
    Venue_KIND_UNSPECIFIED       Venue_Kind = 0
    Venue_KIND_CONCERT_HALL      Venue_Kind = 1
    Venue_KIND_STADIUM           Venue_Kind = 2
    Venue_KIND_BAR               Venue_Kind = 3
    Venue_KIND_OPEN_AIR_FESTIVAL Venue_Kind = 4
)

パッケージレベルの列挙型の場合、定数は列挙型名で始まります。

const (
    Genre_GENRE_UNSPECIFIED   Genre = 0
    Genre_GENRE_ROCK          Genre = 1
    Genre_GENRE_INDIE         Genre = 2
    Genre_GENRE_DRUM_AND_BASS Genre = 3
)

プロトコルバッファコンパイラは、整数値から文字列名へのマップと、名前から値へのマップも生成します。

var Genre_name = map[int32]string{
    0: "GENRE_UNSPECIFIED",
    1: "GENRE_ROCK",
    2: "GENRE_INDIE",
    3: "GENRE_DRUM_AND_BASS",
}
var Genre_value = map[string]int32{
    "GENRE_UNSPECIFIED":   0,
    "GENRE_ROCK":          1,
    "GENRE_INDIE":         2,
    "GENRE_DRUM_AND_BASS": 3,
}

`.proto` 言語では、複数の列挙型シンボルが同じ数値を持つことができます。同じ数値を持つシンボルは同義語です。これらは Go では全く同じように表現され、複数の名前が同じ数値に対応します。逆マッピングには、`.proto` ファイルで最初に現れる名前への数値の単一のエントリが含まれます。

拡張機能 (proto2)

エクステンション定義が与えられた場合：

extend Concert {
  optional int32 promo_id = 123;
}

プロトコルバッファコンパイラは、`E_Promo_id` という名前の`protoreflect.ExtensionType`値を生成します。この値は、メッセージ内の拡張機能にアクセスするために、`proto.GetExtension`、`proto.SetExtension`、`proto.HasExtension`、および`proto.ClearExtension`関数とともに使用できます。`GetExtension`関数と`SetExtension`関数はそれぞれ、拡張機能値の型を含む`interface{}`値を返したり受け入れたりします。

単一のスカラー拡張フィールドの場合、拡張値の型はスカラー値型テーブルからの対応するGo型です。

単一の埋め込みメッセージ拡張フィールドの場合、拡張値の型は `*M` で、`M` はフィールドメッセージ型です。

繰り返し拡張フィールドの場合、拡張値の型は単一の型のスライスです。

例えば、以下の定義が与えられた場合

extend Concert {
  optional int32 singular_int32 = 1;
  repeated bytes repeated_strings = 2;
  optional Band singular_message = 3;
}

拡張値は次のようにアクセスできます。

m := &somepb.Concert{}
proto.SetExtension(m, extpb.E_SingularInt32, int32(1))
proto.SetExtension(m, extpb.E_RepeatedString, []string{"a", "b", "c"})
proto.SetExtension(m, extpb.E_SingularMessage, &extpb.Band{})

v1 := proto.GetExtension(m, extpb.E_SingularInt32).(int32)
v2 := proto.GetExtension(m, extpb.E_RepeatedString).([][]byte)
v3 := proto.GetExtension(m, extpb.E_SingularMessage).(*extpb.Band)

エクステンションは、別の型の中にネストして宣言することができます。たとえば、一般的なパターンは次のようなものです。

message Promo {
  extend Concert {
    optional int32 promo_id = 124;
  }
}

この場合、`ExtensionType` の値は `E_Promo_Concert` という名前になります。

サービス

Go コードジェネレーターは、デフォルトではサービス用の出力を生成しません。 gRPC プラグインを有効にすると（gRPC Go Quickstart guide を参照）、gRPC をサポートするためのコードが生成されます。