生成コードリファレンス

このページでは、protocで.protoファイルをコンパイルする際に、grpcプラグイン、protoc-gen-go-grpcで生成されるコードについて説明します。

.protoファイルでgRPCサービスを定義する方法については、サービス定義を参照してください。

スレッドセーフ：クライアント側のRPC呼び出しとサーバー側のRPCハンドラーはスレッドセーフであり、並行するゴルーチンで実行されることを意図していることに注意してください。ただし、個々のストリームの場合、入出力データは双方向ですがシリアルであることに注意してください。したがって、たとえば、個々のストリームは同時読み取りまたは同時書き込みをサポートしていません（ただし、読み取りは書き込みと安全に同時実行できます）。

生成されたサーバーインターフェースのメソッド

サーバー側では、.protoファイル内の各service Barは、次の関数になります。

func RegisterBarServer(s *grpc.Server, srv BarServer)

アプリケーションは、BarServerインターフェースの具体的な実装を定義し、この関数を使用して（サーバーインスタンスを開始する前に）grpc.Serverインスタンスに登録できます。

単項メソッド

これらのメソッドは、生成されたサービスインターフェースで次のシグネチャを持ちます。

Foo(context.Context, *MsgA) (*MsgB, error)

このコンテキストでは、MsgAはクライアントから送信されたprotobufメッセージであり、MsgBはサーバーから返信されたprotobufメッセージです。

サーバー側のストリーミングメソッド

これらのメソッドは、生成されたサービスインターフェースで次のシグネチャを持ちます。

Foo(*MsgA, <ServiceName>_FooServer) error

このコンテキストでは、MsgAはクライアントからの単一のリクエストであり、<ServiceName>_FooServerパラメーターはMsgBメッセージのサーバーからクライアントへのストリームを表します。

<ServiceName>_FooServerには、grpc.ServerStreamと以下のインターフェースが組み込まれています。

type <ServiceName>_FooServer interface {
	Send(*MsgB) error
	grpc.ServerStream
}

サーバー側のハンドラーは、このパラメーターのSendメソッドを使用して、protobufメッセージのストリームをクライアントに送信できます。サーバーからクライアントへのストリームの終端は、ハンドラーメソッドのreturnによって引き起こされます。

クライアント側のストリーミングメソッド

これらのメソッドは、生成されたサービスインターフェースで次のシグネチャを持ちます。

Foo(<ServiceName>_FooServer) error

このコンテキストでは、<ServiceName>_FooServerは、クライアントからサーバーへのメッセージストリームを読み取り、単一のサーバー応答メッセージを送信するために使用できます。

<ServiceName>_FooServerには、grpc.ServerStreamと以下のインターフェースが組み込まれています。

type <ServiceName>_FooServer interface {
	SendAndClose(*MsgA) error
	Recv() (*MsgB, error)
	grpc.ServerStream
}

サーバー側のハンドラーは、クライアントからのメッセージのフルストリームを受信するために、このパラメーターでRecvを繰り返し呼び出すことができます。Recvは、ストリームの終わりに達すると、(nil, io.EOF)を返します。サーバーからの単一の応答メッセージは、この<ServiceName>_FooServerパラメーターでSendAndCloseメソッドを呼び出すことによって送信されます。SendAndCloseは1回だけ呼び出す必要があることに注意してください。

双方向ストリーミングメソッド

これらのメソッドは、生成されたサービスインターフェースで次のシグネチャを持ちます。

Foo(<ServiceName>_FooServer) error

このコンテキストでは、<ServiceName>_FooServerは、クライアントからサーバーへのメッセージストリームと、サーバーからクライアントへのメッセージストリームの両方にアクセスするために使用できます。<ServiceName>_FooServerには、grpc.ServerStreamと以下のインターフェースが組み込まれています。

type <ServiceName>_FooServer interface {
	Send(*MsgA) error
	Recv() (*MsgB, error)
	grpc.ServerStream
}

サーバー側のハンドラーは、クライアントからサーバーへのメッセージストリームを読み取るために、このパラメーターでRecvを繰り返し呼び出すことができます。Recvは、クライアントからサーバーへのストリームの終わりに達すると、(nil, io.EOF)を返します。サーバーからクライアントへの応答メッセージストリームは、このServiceName>_FooServerパラメーターでSendメソッドを繰り返し呼び出すことによって送信されます。サーバーからクライアントへのストリームの終端は、双方向メソッドハンドラーのreturnによって示されます。

生成されたクライアントインターフェースのメソッド

クライアント側の使用法では、.protoファイル内の各service Barも、func BarClient(cc *grpc.ClientConn) BarClientという関数になり、BarClientインターフェースの具体的な実装を返します（この具体的な実装も生成された.pb.goファイルに存在します）。

単項メソッド

これらのメソッドは、生成されたクライアントスタブで次のシグネチャを持ちます。

(ctx context.Context, in *MsgA, opts ...grpc.CallOption) (*MsgB, error)

このコンテキストでは、MsgAはクライアントからサーバーへの単一のリクエストであり、MsgBにはサーバーから返信された応答が含まれています。

サーバー側のストリーミングメソッド

これらのメソッドは、生成されたクライアントスタブで次のシグネチャを持ちます。

Foo(ctx context.Context, in *MsgA, opts ...grpc.CallOption) (<ServiceName>_FooClient, error)

このコンテキストでは、<ServiceName>_FooClientはMsgBメッセージのサーバーからクライアントへのストリームを表します。

このストリームには、grpc.ClientStreamと以下のインターフェースが組み込まれています。

type <ServiceName>_FooClient interface {
	Recv() (*MsgB, error)
	grpc.ClientStream
}

クライアントがスタブでFooメソッドを呼び出すと、ストリームが開始されます。次に、クライアントは、返された<ServiceName>_FooClient ストリームでRecvメソッドを繰り返し呼び出して、サーバーからクライアントへの応答ストリームを読み取ることができます。このRecvメソッドは、サーバーからクライアントへのストリームが完全に読み取られると、(nil, io.EOF)を返します。

クライアント側のストリーミングメソッド

これらのメソッドは、生成されたクライアントスタブで次のシグネチャを持ちます。

Foo(ctx context.Context, opts ...grpc.CallOption) (<ServiceName>_FooClient, error)

このコンテキストでは、<ServiceName>_FooClientはMsgAメッセージのクライアントからサーバーへのストリームを表します。

<ServiceName>_FooClientには、grpc.ClientStreamと以下のインターフェースが組み込まれています。

type <ServiceName>_FooClient interface {
	Send(*MsgA) error
	CloseAndRecv() (*MsgB, error)
	grpc.ClientStream
}

クライアントがスタブでFooメソッドを呼び出すと、ストリームが開始されます。次に、クライアントは、返された<ServiceName>_FooClientストリームでSendメソッドを繰り返し呼び出して、クライアントからサーバーへのメッセージストリームを送信できます。このストリームのCloseAndRecvメソッドは、クライアントからサーバーへのストリームを閉じて、サーバーから単一の応答メッセージを受信するために、1回だけ呼び出す必要があります。

双方向ストリーミングメソッド

これらのメソッドは、生成されたクライアントスタブで次のシグネチャを持ちます。

Foo(ctx context.Context, opts ...grpc.CallOption) (<ServiceName>_FooClient, error)

このコンテキストでは、<ServiceName>_FooClientは、クライアントからサーバーへのメッセージストリームと、サーバーからクライアントへのメッセージストリームの両方を表します。

<ServiceName>_FooClientには、grpc.ClientStreamと以下のインターフェースが組み込まれています。

type <ServiceName>_FooClient interface {
	Send(*MsgA) error
	Recv() (*MsgB, error)
	grpc.ClientStream
}

クライアントがスタブでFooメソッドを呼び出すと、ストリームが開始されます。次に、クライアントは、返された<SericeName>_FooClientストリームでSendメソッドを繰り返し呼び出して、クライアントからサーバーへのメッセージストリームを送信できます。クライアントは、このストリームでRecvを繰り返し呼び出して、サーバーからクライアントへのメッセージストリーム全体を受信することもできます。

サーバーからクライアントへのストリームの終端は、ストリームのRecvメソッドでの(nil, io.EOF)の戻り値によって示されます。クライアントからサーバーへのストリームの終端は、クライアントがストリームのCloseSendメソッドを呼び出すことによって示すことができます。

パッケージと名前空間

protocコンパイラが--go_out=plugins=grpc:で呼び出されると、proto packageからGoパッケージへの変換は、protoc-gen-goプラグインがgrpcプラグインなしで使用される場合と同じように機能します。

したがって、たとえば、foo.protoがpackage fooにあると宣言した場合、生成されたfoo.pb.goファイルもGoのpackage fooになります。