Go で gRPC を使うためのまとめ

gRPCを使いそうなので記事にまとめておきます。

ちょっとだけ長いので必要なところだけ読めばいいと思います。 あとスマホで見ようとすると重いのでPCで見ることをおすすめします。

今回使うコードはリポジトリに置いてあります。 https://github.com/righ/grpc-go-example/

これはgrpc/grpc-go/ の examples をベースに修正と追記をしたものです。

clone して docker-compose すればコンテナが２つ起動します。

以下の内容はすべてこれらのコンテナが起動している前提なので、手元で試したい方は clone してください。

🌀 とりあえず使ってみる

起動した2つのコンテナ(grpc-server,grpc-client)に入って プログラムをインストールします。

インストールしたプログラムは $GOPATH/bin/ に配置されるのでそのまま実行できます。

• grpc-server
• grpc-client

• $ docker exec -it grpc-server /bin/bash root@82769e87d925:~# go get -u github.com/righ/grpc-go-example/helloworld/greeter_server root@82769e87d925:~# greeter_server 2020/02/01 12:34:44 Received: world 2020/02/01 12:34:51 Received: world
• $ docker exec -it grpc-client /bin/bash root@189290506d75:~# go get -u github.com/righ/grpc-go-example/helloworld/greeter_client root@189290506d75:~# greeter_client 2020/02/01 12:34:44 Greeting: Hello world root@189290506d75:~# greeter_client 2020/02/01 12:34:51 Greeting: Hello world

クライアントプログラムを実行するたびに以下の処理が実行されているだけです。

• リクエストを受け取ったサーバはその内容を表示
• クライアントは返却されたレスポンスを表示

info

• 以降のプログラムも、サーバは grpc-server コンテナ、 クライアントは grpc-client コンテナで動くことを前提に書いています。

この程度の通信プログラムくらいなら自力でも簡単に書くことができますよね。

何故 gRPC を使うと嬉しいのか。 gRPC 自体が高速だというのもあるのですが、別の理由としては Protocol Buffer の存在が大きいです。

📖 Protocol Buffer

まずは簡単な説明を。

Protocol Buffers（プロトコルバッファー）はインタフェース定義言語 (IDL) で構造を定義する通信や永続化での利用を目的としたシリアライズフォーマットであり、Googleにより開発されている。

Protocol Buffers - Wikipedia

gRPCはこの Protocol Buffer で定義された構造を使って通信を行います。

定義は下記(左)のようなテキストファイルです(拡張子を proto とするのが慣例)

• helloworld.proto

  syntax = "proto3";
  
  option java_multiple_files = true;
  option java_package = "io.grpc.examples.helloworld";
  option java_outer_classname = "HelloWorldProto";
  
  package helloworld;
  
  // The greeting service definition.
  service Greeter {
    // Sends a greeting
    rpc SayHello (HelloRequest) returns (HelloReply) {}
  }
  
  // The request message containing the user's name.
  message HelloRequest {
    string name = 1;
  }
  
  // The response message containing the greetings
  message HelloReply {
    string message = 1;
  }
  
  

• helloworld.pb.go

  // Code generated by protoc-gen-go. DO NOT EDIT.
  // source: helloworld.proto
  
  package helloworld
  
  import (
  	context "context"
  	fmt "fmt"
  	proto "github.com/golang/protobuf/proto"
  	grpc "google.golang.org/grpc"
  	codes "google.golang.org/grpc/codes"
  	status "google.golang.org/grpc/status"
  	math "math"
  )
  
  // Reference imports to suppress errors if they are not otherwise used.
  var _ = proto.Marshal
  var _ = fmt.Errorf
  var _ = math.Inf
  
  // This is a compile-time assertion to ensure that this generated file
  // is compatible with the proto package it is being compiled against.
  // A compilation error at this line likely means your copy of the
  // proto package needs to be updated.
  const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package
  
  // The request message containing the user's name.
  type HelloRequest struct {
  	Name                 string   `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
  	XXX_NoUnkeyedLiteral struct{} `json:"-"`
  	XXX_unrecognized     []byte   `json:"-"`
  	XXX_sizecache        int32    `json:"-"`
  }
  
  func (m *HelloRequest) Reset()         { *m = HelloRequest{} }
  func (m *HelloRequest) String() string { return proto.CompactTextString(m) }
  func (*HelloRequest) ProtoMessage()    {}
  func (*HelloRequest) Descriptor() ([]byte, []int) {
  	return fileDescriptor_17b8c58d586b62f2, []int{0}
  }
  
  func (m *HelloRequest) XXX_Unmarshal(b []byte) error {
  	return xxx_messageInfo_HelloRequest.Unmarshal(m, b)
  }
  func (m *HelloRequest) XXX_Marshal(b []byte, deterministic bool) ([]byte, error) {
  	return xxx_messageInfo_HelloRequest.Marshal(b, m, deterministic)
  }
  func (m *HelloRequest) XXX_Merge(src proto.Message) {
  	xxx_messageInfo_HelloRequest.Merge(m, src)
  }
  func (m *HelloRequest) XXX_Size() int {
  	return xxx_messageInfo_HelloRequest.Size(m)
  }
  func (m *HelloRequest) XXX_DiscardUnknown() {
  	xxx_messageInfo_HelloRequest.DiscardUnknown(m)
  }
  
  var xxx_messageInfo_HelloRequest proto.InternalMessageInfo
  
  func (m *HelloRequest) GetName() string {
  	if m != nil {
  		return m.Name
  	}
  	return ""
  }
  
  // The response message containing the greetings
  type HelloReply struct {
  	Message              string   `protobuf:"bytes,1,opt,name=message,proto3" json:"message,omitempty"`
  	XXX_NoUnkeyedLiteral struct{} `json:"-"`
  	XXX_unrecognized     []byte   `json:"-"`
  	XXX_sizecache        int32    `json:"-"`
  }
  
  func (m *HelloReply) Reset()         { *m = HelloReply{} }
  func (m *HelloReply) String() string { return proto.CompactTextString(m) }
  func (*HelloReply) ProtoMessage()    {}
  func (*HelloReply) Descriptor() ([]byte, []int) {
  	return fileDescriptor_17b8c58d586b62f2, []int{1}
  }
  
  func (m *HelloReply) XXX_Unmarshal(b []byte) error {
  	return xxx_messageInfo_HelloReply.Unmarshal(m, b)
  }
  func (m *HelloReply) XXX_Marshal(b []byte, deterministic bool) ([]byte, error) {
  	return xxx_messageInfo_HelloReply.Marshal(b, m, deterministic)
  }
  func (m *HelloReply) XXX_Merge(src proto.Message) {
  	xxx_messageInfo_HelloReply.Merge(m, src)
  }
  func (m *HelloReply) XXX_Size() int {
  	return xxx_messageInfo_HelloReply.Size(m)
  }
  func (m *HelloReply) XXX_DiscardUnknown() {
  	xxx_messageInfo_HelloReply.DiscardUnknown(m)
  }
  
  var xxx_messageInfo_HelloReply proto.InternalMessageInfo
  
  func (m *HelloReply) GetMessage() string {
  	if m != nil {
  		return m.Message
  	}
  	return ""
  }
  
  func init() {
  	proto.RegisterType((*HelloRequest)(nil), "helloworld.HelloRequest")
  	proto.RegisterType((*HelloReply)(nil), "helloworld.HelloReply")
  }
  
  func init() { proto.RegisterFile("helloworld.proto", fileDescriptor_17b8c58d586b62f2) }
  
  var fileDescriptor_17b8c58d586b62f2 = []byte{
  	// 175 bytes of a gzipped FileDescriptorProto
  	0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0xff, 0xe2, 0x12, 0xc8, 0x48, 0xcd, 0xc9,
  	0xc9, 0x2f, 0xcf, 0x2f, 0xca, 0x49, 0xd1, 0x2b, 0x28, 0xca, 0x2f, 0xc9, 0x17, 0xe2, 0x42, 0x88,
  	0x28, 0x29, 0x71, 0xf1, 0x78, 0x80, 0x78, 0x41, 0xa9, 0x85, 0xa5, 0xa9, 0xc5, 0x25, 0x42, 0x42,
  	0x5c, 0x2c, 0x79, 0x89, 0xb9, 0xa9, 0x12, 0x8c, 0x0a, 0x8c, 0x1a, 0x9c, 0x41, 0x60, 0xb6, 0x92,
  	0x1a, 0x17, 0x17, 0x54, 0x4d, 0x41, 0x4e, 0xa5, 0x90, 0x04, 0x17, 0x7b, 0x6e, 0x6a, 0x71, 0x71,
  	0x62, 0x3a, 0x4c, 0x11, 0x8c, 0x6b, 0xe4, 0xc9, 0xc5, 0xee, 0x5e, 0x94, 0x9a, 0x5a, 0x92, 0x5a,
  	0x24, 0x64, 0xc7, 0xc5, 0x11, 0x9c, 0x58, 0x09, 0xd6, 0x25, 0x24, 0xa1, 0x87, 0xe4, 0x02, 0x64,
  	0xcb, 0xa4, 0xc4, 0xb0, 0xc8, 0x14, 0xe4, 0x54, 0x2a, 0x31, 0x38, 0x19, 0x70, 0x49, 0x67, 0xe6,
  	0xeb, 0xa5, 0x17, 0x15, 0x24, 0xeb, 0xa5, 0x56, 0x24, 0xe6, 0x16, 0xe4, 0xa4, 0x16, 0x23, 0xa9,
  	0x75, 0xe2, 0x07, 0x2b, 0x0e, 0x07, 0xb1, 0x03, 0x40, 0x5e, 0x0a, 0x60, 0x4c, 0x62, 0x03, 0xfb,
  	0xcd, 0x18, 0x10, 0x00, 0x00, 0xff, 0xff, 0x0f, 0xb7, 0xcd, 0xf2, 0xef, 0x00, 0x00, 0x00,
  }
  
  // Reference imports to suppress errors if they are not otherwise used.
  var _ context.Context
  var _ grpc.ClientConnInterface
  
  // This is a compile-time assertion to ensure that this generated file
  // is compatible with the grpc package it is being compiled against.
  const _ = grpc.SupportPackageIsVersion6
  
  // GreeterClient is the client API for Greeter service.
  //
  // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.
  type GreeterClient interface {
  	// Sends a greeting
  	SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloReply, error)
  }
  
  type greeterClient struct {
  	cc grpc.ClientConnInterface
  }
  
  func NewGreeterClient(cc grpc.ClientConnInterface) GreeterClient {
  	return &greeterClient{cc}
  }
  
  func (c *greeterClient) SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloReply, error) {
  	out := new(HelloReply)
  	err := c.cc.Invoke(ctx, "/helloworld.Greeter/SayHello", in, out, opts...)
  	if err != nil {
  		return nil, err
  	}
  	return out, nil
  }
  
  // GreeterServer is the server API for Greeter service.
  type GreeterServer interface {
  	// Sends a greeting
  	SayHello(context.Context, *HelloRequest) (*HelloReply, error)
  }
  
  // UnimplementedGreeterServer can be embedded to have forward compatible implementations.
  type UnimplementedGreeterServer struct {
  }
  
  func (*UnimplementedGreeterServer) SayHello(ctx context.Context, req *HelloRequest) (*HelloReply, error) {
  	return nil, status.Errorf(codes.Unimplemented, "method SayHello not implemented")
  }
  
  func RegisterGreeterServer(s *grpc.Server, srv GreeterServer) {
  	s.RegisterService(&_Greeter_serviceDesc, srv)
  }
  
  func _Greeter_SayHello_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
  	in := new(HelloRequest)
  	if err := dec(in); err != nil {
  		return nil, err
  	}
  	if interceptor == nil {
  		return srv.(GreeterServer).SayHello(ctx, in)
  	}
  	info := &grpc.UnaryServerInfo{
  		Server:     srv,
  		FullMethod: "/helloworld.Greeter/SayHello",
  	}
  	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
  		return srv.(GreeterServer).SayHello(ctx, req.(*HelloRequest))
  	}
  	return interceptor(ctx, in, info, handler)
  }
  
  var _Greeter_serviceDesc = grpc.ServiceDesc{
  	ServiceName: "helloworld.Greeter",
  	HandlerType: (*GreeterServer)(nil),
  	Methods: []grpc.MethodDesc{
  		{
  			MethodName: "SayHello",
  			Handler:    _Greeter_SayHello_Handler,
  		},
  	},
  	Streams:  []grpc.StreamDesc{},
  	Metadata: "helloworld.proto",
  }
  
  

この定義をもとにコードを自動生成(上記右)して、自動生成されたコード(パラメータなど)を使って実装することで、定義した構造を用いて通信できるというわけです。

このコードを自動生成するのが protoc コマンドです。

Macであれば brew を使ってインストールすることもできますが、 それ以外の環境を利用する場合は Releases からダウンロードしてきましょう

今回は 簡単なスクリプト を使ってインストールします。これで protoc コマンドが使えるようになります。

warning

• このスクリプトの中では Goのコードを生成するための protoc-gen-go も同時にインストールしています
• これがない状態でコードを生成しようとすると次のようなエラーになるので手動でインストールする場合は注意してください。
• protoc-gen-go: program not found or is not executable

syntax

• Protocol Buffer のバージョン
• 現時点(2020-02)では 3 が最新。

option

• protoc に与えるオプション
• 現状 Golang 向けのオプションは go_package だけっぽいです。

• info

  • option go_package = "../ptypes"; のように指定して以下のように実行すれば ../ptypes/ に pb ファイルが出力されます。
  • ~/helloworld/helloworld# protoc --go_out=plugins=grpc:. helloworld.proto ~/helloworld/helloworld# ls ../ptypes/ helloworld.pb.go
  • ちなみに --go_out=plugins=grpc:{パス} を起点に出力されるため go_package にフルパスを指定するなら、パスには / を指定します。

• 参考
  • Packages and input paths - golang/protobuf
  • descriptor.proto - protocolbuffers/protobuf
  • Proto3 Language Guide（和訳） - Qiita

package

• パッケージ名
• (Golangでは)Goファイルのパッケージ名になるため出力先のディレクトリ名と合わせるべき

import

• 別ファイルの定義を取り込む。

message

• 通信に利用されるパラメータやレスポンスの型定義
• (Golangでは)Messageに対応する構造体が作られる
  • Message の各フィールドは構造体のフィールドに対応する
• フィールドは型を持つ
  • 配列(Array)を表現する場合は repeated を使う
  • マップを表現する場合は map を使う
• https://developers.google.com/protocol-buffers/docs/proto3

service

• 機能をまとめた単位。サービスには RPC が紐づく。
• (Golangでは)定義したServiceの数だけ Server, Client のインタフェースが作られる
• Serviceの rpc フィールドはそれぞれのインタフェースのメソッドとして登録される

参考

• https://qiita.com/yugui/items/160737021d25d761b353

⭐️ RPC types

gRPCは4種類の通信方法を提供します。

というと身構えてしまいそうですが、 簡単に言うと「 stream を指定するかしないか」 「クライアント側で指定するかサーバ側で指定するか」で名称が分かれているだけです。

• 種類
• stream指定
• 例

• Unary RPC
• sequenceDiagram participant client participant server client->>server: Request server-->>client: Response

• Server streaming RPC
• サーバー
• sequenceDiagram participant client participant server client->>server: Request server-->>client: Response server-->>client: Response

• Client streaming RPC
• クライアント
• sequenceDiagram participant client participant server client->>server: Request client->>server: Request server-->>client: Response

• Bidirectional streaming
• 両方
• sequenceDiagram participant client participant server client->>server: Request server-->>client: Response server-->>client: Response client->>server: Request client->>server: Request client->>server: Request

ではストリーミングとは何かというと、 連続した通信(リクエスト,レスポンス)で、これまでの単発の通信と対比する呼称です。

gRPCはリクエスト、レスポンスともにデータサイズに上限があります。やり取りするデータが可変長で巨大になる可能性がある場合はストリーミングによって通信を分割することが望ましいです。

🌚 Unary RPC

1つのリクエストに対して1つのレスポンスを返す最も基本的なRPCです。

Unary RPC - gRPC

クライアント、サーバともに stream を指定しなければデフォルトでこれになります。

先程も見ましたが、定義ファイルをもう一度確認しておきましょう。

• helloworld.proto

  syntax = "proto3";
  
  option java_multiple_files = true;
  option java_package = "io.grpc.examples.helloworld";
  option java_outer_classname = "HelloWorldProto";
  
  package helloworld;
  
  // The greeting service definition.
  service Greeter {
    // Sends a greeting
    rpc SayHello (HelloRequest) returns (HelloReply) {}
  }
  
  // The request message containing the user's name.
  message HelloRequest {
    string name = 1;
  }
  
  // The response message containing the greetings
  message HelloReply {
    string message = 1;
  }
  
  

• helloworld.pb.go

  // Code generated by protoc-gen-go. DO NOT EDIT.
  // source: helloworld.proto
  
  package helloworld
  
  import (
  	context "context"
  	fmt "fmt"
  	proto "github.com/golang/protobuf/proto"
  	grpc "google.golang.org/grpc"
  	codes "google.golang.org/grpc/codes"
  	status "google.golang.org/grpc/status"
  	math "math"
  )
  
  // Reference imports to suppress errors if they are not otherwise used.
  var _ = proto.Marshal
  var _ = fmt.Errorf
  var _ = math.Inf
  
  // This is a compile-time assertion to ensure that this generated file
  // is compatible with the proto package it is being compiled against.
  // A compilation error at this line likely means your copy of the
  // proto package needs to be updated.
  const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package
  
  // The request message containing the user's name.
  type HelloRequest struct {
  	Name                 string   `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
  	XXX_NoUnkeyedLiteral struct{} `json:"-"`
  	XXX_unrecognized     []byte   `json:"-"`
  	XXX_sizecache        int32    `json:"-"`
  }
  
  func (m *HelloRequest) Reset()         { *m = HelloRequest{} }
  func (m *HelloRequest) String() string { return proto.CompactTextString(m) }
  func (*HelloRequest) ProtoMessage()    {}
  func (*HelloRequest) Descriptor() ([]byte, []int) {
  	return fileDescriptor_17b8c58d586b62f2, []int{0}
  }
  
  func (m *HelloRequest) XXX_Unmarshal(b []byte) error {
  	return xxx_messageInfo_HelloRequest.Unmarshal(m, b)
  }
  func (m *HelloRequest) XXX_Marshal(b []byte, deterministic bool) ([]byte, error) {
  	return xxx_messageInfo_HelloRequest.Marshal(b, m, deterministic)
  }
  func (m *HelloRequest) XXX_Merge(src proto.Message) {
  	xxx_messageInfo_HelloRequest.Merge(m, src)
  }
  func (m *HelloRequest) XXX_Size() int {
  	return xxx_messageInfo_HelloRequest.Size(m)
  }
  func (m *HelloRequest) XXX_DiscardUnknown() {
  	xxx_messageInfo_HelloRequest.DiscardUnknown(m)
  }
  
  var xxx_messageInfo_HelloRequest proto.InternalMessageInfo
  
  func (m *HelloRequest) GetName() string {
  	if m != nil {
  		return m.Name
  	}
  	return ""
  }
  
  // The response message containing the greetings
  type HelloReply struct {
  	Message              string   `protobuf:"bytes,1,opt,name=message,proto3" json:"message,omitempty"`
  	XXX_NoUnkeyedLiteral struct{} `json:"-"`
  	XXX_unrecognized     []byte   `json:"-"`
  	XXX_sizecache        int32    `json:"-"`
  }
  
  func (m *HelloReply) Reset()         { *m = HelloReply{} }
  func (m *HelloReply) String() string { return proto.CompactTextString(m) }
  func (*HelloReply) ProtoMessage()    {}
  func (*HelloReply) Descriptor() ([]byte, []int) {
  	return fileDescriptor_17b8c58d586b62f2, []int{1}
  }
  
  func (m *HelloReply) XXX_Unmarshal(b []byte) error {
  	return xxx_messageInfo_HelloReply.Unmarshal(m, b)
  }
  func (m *HelloReply) XXX_Marshal(b []byte, deterministic bool) ([]byte, error) {
  	return xxx_messageInfo_HelloReply.Marshal(b, m, deterministic)
  }
  func (m *HelloReply) XXX_Merge(src proto.Message) {
  	xxx_messageInfo_HelloReply.Merge(m, src)
  }
  func (m *HelloReply) XXX_Size() int {
  	return xxx_messageInfo_HelloReply.Size(m)
  }
  func (m *HelloReply) XXX_DiscardUnknown() {
  	xxx_messageInfo_HelloReply.DiscardUnknown(m)
  }
  
  var xxx_messageInfo_HelloReply proto.InternalMessageInfo
  
  func (m *HelloReply) GetMessage() string {
  	if m != nil {
  		return m.Message
  	}
  	return ""
  }
  
  func init() {
  	proto.RegisterType((*HelloRequest)(nil), "helloworld.HelloRequest")
  	proto.RegisterType((*HelloReply)(nil), "helloworld.HelloReply")
  }
  
  func init() { proto.RegisterFile("helloworld.proto", fileDescriptor_17b8c58d586b62f2) }
  
  var fileDescriptor_17b8c58d586b62f2 = []byte{
  	// 175 bytes of a gzipped FileDescriptorProto
  	0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0xff, 0xe2, 0x12, 0xc8, 0x48, 0xcd, 0xc9,
  	0xc9, 0x2f, 0xcf, 0x2f, 0xca, 0x49, 0xd1, 0x2b, 0x28, 0xca, 0x2f, 0xc9, 0x17, 0xe2, 0x42, 0x88,
  	0x28, 0x29, 0x71, 0xf1, 0x78, 0x80, 0x78, 0x41, 0xa9, 0x85, 0xa5, 0xa9, 0xc5, 0x25, 0x42, 0x42,
  	0x5c, 0x2c, 0x79, 0x89, 0xb9, 0xa9, 0x12, 0x8c, 0x0a, 0x8c, 0x1a, 0x9c, 0x41, 0x60, 0xb6, 0x92,
  	0x1a, 0x17, 0x17, 0x54, 0x4d, 0x41, 0x4e, 0xa5, 0x90, 0x04, 0x17, 0x7b, 0x6e, 0x6a, 0x71, 0x71,
  	0x62, 0x3a, 0x4c, 0x11, 0x8c, 0x6b, 0xe4, 0xc9, 0xc5, 0xee, 0x5e, 0x94, 0x9a, 0x5a, 0x92, 0x5a,
  	0x24, 0x64, 0xc7, 0xc5, 0x11, 0x9c, 0x58, 0x09, 0xd6, 0x25, 0x24, 0xa1, 0x87, 0xe4, 0x02, 0x64,
  	0xcb, 0xa4, 0xc4, 0xb0, 0xc8, 0x14, 0xe4, 0x54, 0x2a, 0x31, 0x38, 0x19, 0x70, 0x49, 0x67, 0xe6,
  	0xeb, 0xa5, 0x17, 0x15, 0x24, 0xeb, 0xa5, 0x56, 0x24, 0xe6, 0x16, 0xe4, 0xa4, 0x16, 0x23, 0xa9,
  	0x75, 0xe2, 0x07, 0x2b, 0x0e, 0x07, 0xb1, 0x03, 0x40, 0x5e, 0x0a, 0x60, 0x4c, 0x62, 0x03, 0xfb,
  	0xcd, 0x18, 0x10, 0x00, 0x00, 0xff, 0xff, 0x0f, 0xb7, 0xcd, 0xf2, 0xef, 0x00, 0x00, 0x00,
  }
  
  // Reference imports to suppress errors if they are not otherwise used.
  var _ context.Context
  var _ grpc.ClientConnInterface
  
  // This is a compile-time assertion to ensure that this generated file
  // is compatible with the grpc package it is being compiled against.
  const _ = grpc.SupportPackageIsVersion6
  
  // GreeterClient is the client API for Greeter service.
  //
  // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.
  type GreeterClient interface {
  	// Sends a greeting
  	SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloReply, error)
  }
  
  type greeterClient struct {
  	cc grpc.ClientConnInterface
  }
  
  func NewGreeterClient(cc grpc.ClientConnInterface) GreeterClient {
  	return &greeterClient{cc}
  }
  
  func (c *greeterClient) SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloReply, error) {
  	out := new(HelloReply)
  	err := c.cc.Invoke(ctx, "/helloworld.Greeter/SayHello", in, out, opts...)
  	if err != nil {
  		return nil, err
  	}
  	return out, nil
  }
  
  // GreeterServer is the server API for Greeter service.
  type GreeterServer interface {
  	// Sends a greeting
  	SayHello(context.Context, *HelloRequest) (*HelloReply, error)
  }
  
  // UnimplementedGreeterServer can be embedded to have forward compatible implementations.
  type UnimplementedGreeterServer struct {
  }
  
  func (*UnimplementedGreeterServer) SayHello(ctx context.Context, req *HelloRequest) (*HelloReply, error) {
  	return nil, status.Errorf(codes.Unimplemented, "method SayHello not implemented")
  }
  
  func RegisterGreeterServer(s *grpc.Server, srv GreeterServer) {
  	s.RegisterService(&_Greeter_serviceDesc, srv)
  }
  
  func _Greeter_SayHello_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
  	in := new(HelloRequest)
  	if err := dec(in); err != nil {
  		return nil, err
  	}
  	if interceptor == nil {
  		return srv.(GreeterServer).SayHello(ctx, in)
  	}
  	info := &grpc.UnaryServerInfo{
  		Server:     srv,
  		FullMethod: "/helloworld.Greeter/SayHello",
  	}
  	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
  		return srv.(GreeterServer).SayHello(ctx, req.(*HelloRequest))
  	}
  	return interceptor(ctx, in, info, handler)
  }
  
  var _Greeter_serviceDesc = grpc.ServiceDesc{
  	ServiceName: "helloworld.Greeter",
  	HandlerType: (*GreeterServer)(nil),
  	Methods: []grpc.MethodDesc{
  		{
  			MethodName: "SayHello",
  			Handler:    _Greeter_SayHello_Handler,
  		},
  	},
  	Streams:  []grpc.StreamDesc{},
  	Metadata: "helloworld.proto",
  }
  
  

これらを使ってサーバとクライアントのコードを書いていきます。

• greeter_server/main.go

  package main
  
  import (
  	"context"
  	"log"
  	"net"
  
  	pb "github.com/righ/grpc-go-example/helloworld/helloworld"
  	"google.golang.org/grpc"
  )
  
  const (
  	port = ":50051"
  )
  
  // server is used to implement helloworld.GreeterServer.
  type server struct {
  	pb.UnimplementedGreeterServer
  }
  
  // SayHello implements helloworld.GreeterServer
  func (s *server) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
  	log.Printf("Received: %v", in.GetName())
  	return &pb.HelloReply{Message: "Hello " + in.GetName()}, nil
  }
  
  func main() {
  	lis, err := net.Listen("tcp", port)
  	if err != nil {
  		log.Fatalf("failed to listen: %v", err)
  	}
  	s := grpc.NewServer()
  	pb.RegisterGreeterServer(s, &server{})
  	if err := s.Serve(lis); err != nil {
  		log.Fatalf("failed to serve: %v", err)
  	}
  }
  
  

• greeter_client/main.go

  package main
  
  import (
  	"context"
  	"log"
  	"os"
  	"time"
  
  	pb "github.com/righ/grpc-go-example/helloworld/helloworld"
  	"google.golang.org/grpc"
  )
  
  const (
  	address     = "grpc-server:50051"
  	defaultName = "world"
  )
  
  func main() {
  	// Set up a connection to the server.
  	conn, err := grpc.Dial(address, grpc.WithInsecure(), grpc.WithBlock())
  	if err != nil {
  		log.Fatalf("did not connect: %v", err)
  	}
  	defer conn.Close()
  	c := pb.NewGreeterClient(conn)
  
  	// Contact the server and print out its response.
  	name := defaultName
  	if len(os.Args) > 1 {
  		name = os.Args[1]
  	}
  	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
  	defer cancel()
  	r, err := c.SayHello(ctx, &pb.HelloRequest{Name: name})
  	if err != nil {
  		log.Fatalf("could not greet: %v", err)
  	}
  	log.Printf("Greeting: %s", r.GetMessage())
  }
  
  

• これは以降全てに共通することですが、サーバ側のコードでは pb.Register{Service名}Server 関数を使って「grpcのサーバ」と「サービス」を紐付けるわけですが、 サービスには上述したインタフェースを引数に取るため、構造体には rpc に相当するメソッドが定義されている必要があります。 Unary RPC では サーバ側のRPCメソッド はリクエストのパラメータとして構造体を受け取って レスポンスとして構造体を返却するだけです。
• Unary RPC のクライアント側コードは更にシンプルで pb.New{Service名}Client で作成したクライアントから呼び出したい rpc のメソッドを呼び出すだけです。 サーバと違い、レスポンスを返却値として返すだけなのでメソッドを実装する必要はありません。

これは Unary RPC に限った話ではないですが、サーバ側のインタフェースを満たす空の構造体(Unimplemented{サービス名}Server)が自動的に生成されるので、 それを使えばひとまずサーバとして動くようになります。

今回のexampleのように、これ(UnimplementedServer)を埋め込んだ構造体を自分で定義して、 必要なメソッドを追加していくというのも良さそうです。

実装すべき機能が多い場合は便利ですね。

warning

• Unary RPC は最も基本的な gRPC ではありますが、後述する RPC と引数が異なるので注意してください。

利用例は最初のセクションを参照してください。

🌜 Server streaming RPC

1つのリクエストに対して、複数(N)のレスポンスを返します。

Server streaming RPC - gRPC

まずはproto定義と自動生成ファイル。 レスポンスにだけ stream が指定されています。

• goodnightworld.proto

  syntax = "proto3";
  
  package goodnightworld;
  
  // The greeting service definition.
  service Greeter {
    // Sends a greeting
    rpc SayGoodnight (GoodnightRequest) returns (stream GoodnightReply) {}
  }
  
  // The request message containing the user's name.
  message GoodnightRequest {
    string name = 1;
  }
  
  // The response message containing the greetings
  message GoodnightReply {
    string message = 1;
  }
  
  

• goodnightworld.pb.go

  // Code generated by protoc-gen-go. DO NOT EDIT.
  // source: goodnightworld.proto
  
  package goodnightworld
  
  import (
  	context "context"
  	fmt "fmt"
  	proto "github.com/golang/protobuf/proto"
  	grpc "google.golang.org/grpc"
  	codes "google.golang.org/grpc/codes"
  	status "google.golang.org/grpc/status"
  	math "math"
  )
  
  // Reference imports to suppress errors if they are not otherwise used.
  var _ = proto.Marshal
  var _ = fmt.Errorf
  var _ = math.Inf
  
  // This is a compile-time assertion to ensure that this generated file
  // is compatible with the proto package it is being compiled against.
  // A compilation error at this line likely means your copy of the
  // proto package needs to be updated.
  const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package
  
  // The request message containing the user's name.
  type GoodnightRequest struct {
  	Name                 string   `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
  	XXX_NoUnkeyedLiteral struct{} `json:"-"`
  	XXX_unrecognized     []byte   `json:"-"`
  	XXX_sizecache        int32    `json:"-"`
  }
  
  func (m *GoodnightRequest) Reset()         { *m = GoodnightRequest{} }
  func (m *GoodnightRequest) String() string { return proto.CompactTextString(m) }
  func (*GoodnightRequest) ProtoMessage()    {}
  func (*GoodnightRequest) Descriptor() ([]byte, []int) {
  	return fileDescriptor_a27943471a8d8b0a, []int{0}
  }
  
  func (m *GoodnightRequest) XXX_Unmarshal(b []byte) error {
  	return xxx_messageInfo_GoodnightRequest.Unmarshal(m, b)
  }
  func (m *GoodnightRequest) XXX_Marshal(b []byte, deterministic bool) ([]byte, error) {
  	return xxx_messageInfo_GoodnightRequest.Marshal(b, m, deterministic)
  }
  func (m *GoodnightRequest) XXX_Merge(src proto.Message) {
  	xxx_messageInfo_GoodnightRequest.Merge(m, src)
  }
  func (m *GoodnightRequest) XXX_Size() int {
  	return xxx_messageInfo_GoodnightRequest.Size(m)
  }
  func (m *GoodnightRequest) XXX_DiscardUnknown() {
  	xxx_messageInfo_GoodnightRequest.DiscardUnknown(m)
  }
  
  var xxx_messageInfo_GoodnightRequest proto.InternalMessageInfo
  
  func (m *GoodnightRequest) GetName() string {
  	if m != nil {
  		return m.Name
  	}
  	return ""
  }
  
  // The response message containing the greetings
  type GoodnightReply struct {
  	Message              string   `protobuf:"bytes,1,opt,name=message,proto3" json:"message,omitempty"`
  	XXX_NoUnkeyedLiteral struct{} `json:"-"`
  	XXX_unrecognized     []byte   `json:"-"`
  	XXX_sizecache        int32    `json:"-"`
  }
  
  func (m *GoodnightReply) Reset()         { *m = GoodnightReply{} }
  func (m *GoodnightReply) String() string { return proto.CompactTextString(m) }
  func (*GoodnightReply) ProtoMessage()    {}
  func (*GoodnightReply) Descriptor() ([]byte, []int) {
  	return fileDescriptor_a27943471a8d8b0a, []int{1}
  }
  
  func (m *GoodnightReply) XXX_Unmarshal(b []byte) error {
  	return xxx_messageInfo_GoodnightReply.Unmarshal(m, b)
  }
  func (m *GoodnightReply) XXX_Marshal(b []byte, deterministic bool) ([]byte, error) {
  	return xxx_messageInfo_GoodnightReply.Marshal(b, m, deterministic)
  }
  func (m *GoodnightReply) XXX_Merge(src proto.Message) {
  	xxx_messageInfo_GoodnightReply.Merge(m, src)
  }
  func (m *GoodnightReply) XXX_Size() int {
  	return xxx_messageInfo_GoodnightReply.Size(m)
  }
  func (m *GoodnightReply) XXX_DiscardUnknown() {
  	xxx_messageInfo_GoodnightReply.DiscardUnknown(m)
  }
  
  var xxx_messageInfo_GoodnightReply proto.InternalMessageInfo
  
  func (m *GoodnightReply) GetMessage() string {
  	if m != nil {
  		return m.Message
  	}
  	return ""
  }
  
  func init() {
  	proto.RegisterType((*GoodnightRequest)(nil), "goodnightworld.GoodnightRequest")
  	proto.RegisterType((*GoodnightReply)(nil), "goodnightworld.GoodnightReply")
  }
  
  func init() { proto.RegisterFile("goodnightworld.proto", fileDescriptor_a27943471a8d8b0a) }
  
  var fileDescriptor_a27943471a8d8b0a = []byte{
  	// 148 bytes of a gzipped FileDescriptorProto
  	0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0xff, 0xe2, 0x12, 0x49, 0xcf, 0xcf, 0x4f,
  	0xc9, 0xcb, 0x4c, 0xcf, 0x28, 0x29, 0xcf, 0x2f, 0xca, 0x49, 0xd1, 0x2b, 0x28, 0xca, 0x2f, 0xc9,
  	0x17, 0xe2, 0x43, 0x15, 0x55, 0x52, 0xe3, 0x12, 0x70, 0x87, 0x89, 0x04, 0xa5, 0x16, 0x96, 0xa6,
  	0x16, 0x97, 0x08, 0x09, 0x71, 0xb1, 0xe4, 0x25, 0xe6, 0xa6, 0x4a, 0x30, 0x2a, 0x30, 0x6a, 0x70,
  	0x06, 0x81, 0xd9, 0x4a, 0x5a, 0x5c, 0x7c, 0x48, 0xea, 0x0a, 0x72, 0x2a, 0x85, 0x24, 0xb8, 0xd8,
  	0x73, 0x53, 0x8b, 0x8b, 0x13, 0xd3, 0x61, 0x0a, 0x61, 0x5c, 0xa3, 0x78, 0x2e, 0x76, 0xf7, 0xa2,
  	0xd4, 0xd4, 0x92, 0xd4, 0x22, 0xa1, 0x10, 0x2e, 0x9e, 0xe0, 0xc4, 0x4a, 0xb8, 0x4e, 0x21, 0x05,
  	0x3d, 0x34, 0x57, 0xa1, 0x5b, 0x2e, 0x25, 0x87, 0x47, 0x45, 0x41, 0x4e, 0xa5, 0x12, 0x83, 0x01,
  	0x63, 0x12, 0x1b, 0xd8, 0x2f, 0xc6, 0x80, 0x00, 0x00, 0x00, 0xff, 0xff, 0x68, 0xae, 0x2b, 0xc8,
  	0xe3, 0x00, 0x00, 0x00,
  }
  
  // Reference imports to suppress errors if they are not otherwise used.
  var _ context.Context
  var _ grpc.ClientConnInterface
  
  // This is a compile-time assertion to ensure that this generated file
  // is compatible with the grpc package it is being compiled against.
  const _ = grpc.SupportPackageIsVersion6
  
  // GreeterClient is the client API for Greeter service.
  //
  // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.
  type GreeterClient interface {
  	// Sends a greeting
  	SayGoodnight(ctx context.Context, in *GoodnightRequest, opts ...grpc.CallOption) (Greeter_SayGoodnightClient, error)
  }
  
  type greeterClient struct {
  	cc grpc.ClientConnInterface
  }
  
  func NewGreeterClient(cc grpc.ClientConnInterface) GreeterClient {
  	return &greeterClient{cc}
  }
  
  func (c *greeterClient) SayGoodnight(ctx context.Context, in *GoodnightRequest, opts ...grpc.CallOption) (Greeter_SayGoodnightClient, error) {
  	stream, err := c.cc.NewStream(ctx, &_Greeter_serviceDesc.Streams[0], "/goodnightworld.Greeter/SayGoodnight", opts...)
  	if err != nil {
  		return nil, err
  	}
  	x := &greeterSayGoodnightClient{stream}
  	if err := x.ClientStream.SendMsg(in); err != nil {
  		return nil, err
  	}
  	if err := x.ClientStream.CloseSend(); err != nil {
  		return nil, err
  	}
  	return x, nil
  }
  
  type Greeter_SayGoodnightClient interface {
  	Recv() (*GoodnightReply, error)
  	grpc.ClientStream
  }
  
  type greeterSayGoodnightClient struct {
  	grpc.ClientStream
  }
  
  func (x *greeterSayGoodnightClient) Recv() (*GoodnightReply, error) {
  	m := new(GoodnightReply)
  	if err := x.ClientStream.RecvMsg(m); err != nil {
  		return nil, err
  	}
  	return m, nil
  }
  
  // GreeterServer is the server API for Greeter service.
  type GreeterServer interface {
  	// Sends a greeting
  	SayGoodnight(*GoodnightRequest, Greeter_SayGoodnightServer) error
  }
  
  // UnimplementedGreeterServer can be embedded to have forward compatible implementations.
  type UnimplementedGreeterServer struct {
  }
  
  func (*UnimplementedGreeterServer) SayGoodnight(req *GoodnightRequest, srv Greeter_SayGoodnightServer) error {
  	return status.Errorf(codes.Unimplemented, "method SayGoodnight not implemented")
  }
  
  func RegisterGreeterServer(s *grpc.Server, srv GreeterServer) {
  	s.RegisterService(&_Greeter_serviceDesc, srv)
  }
  
  func _Greeter_SayGoodnight_Handler(srv interface{}, stream grpc.ServerStream) error {
  	m := new(GoodnightRequest)
  	if err := stream.RecvMsg(m); err != nil {
  		return err
  	}
  	return srv.(GreeterServer).SayGoodnight(m, &greeterSayGoodnightServer{stream})
  }
  
  type Greeter_SayGoodnightServer interface {
  	Send(*GoodnightReply) error
  	grpc.ServerStream
  }
  
  type greeterSayGoodnightServer struct {
  	grpc.ServerStream
  }
  
  func (x *greeterSayGoodnightServer) Send(m *GoodnightReply) error {
  	return x.ServerStream.SendMsg(m)
  }
  
  var _Greeter_serviceDesc = grpc.ServiceDesc{
  	ServiceName: "goodnightworld.Greeter",
  	HandlerType: (*GreeterServer)(nil),
  	Methods:     []grpc.MethodDesc{},
  	Streams: []grpc.StreamDesc{
  		{
  			StreamName:    "SayGoodnight",
  			Handler:       _Greeter_SayGoodnight_Handler,
  			ServerStreams: true,
  		},
  	},
  	Metadata: "goodnightworld.proto",
  }
  
  

今回プログラムの概要は以下です。

• クライアントは名前をサーバに一度だけ送信する
• サーバは受け取った名前を使って挨拶を組み立てて3回連続で返却する
  • デバッグで標準出力にも表示する
• クライアントはサーバから受け取ったメッセージを標準出力に表示する

実用性は全くありません。

• greeter_server/main.go

  package main
  
  import (
  	"log"
  	"net"
  
  	pb "github.com/righ/grpc-go-example/goodnightworld/goodnightworld"
  	"google.golang.org/grpc"
  )
  
  const (
  	port = ":50051"
  )
  
  // server is used to implement goodnightworld.GreeterServer.
  type server struct {
  	pb.UnimplementedGreeterServer
  }
  
  // SayGoodnight implements goodnightworld.GreeterServer
  func (s *server) SayGoodnight(in *pb.GoodnightRequest, srv pb.Greeter_SayGoodnightServer) error {
  	log.Printf("Received: %s", in.GetName())
  	srv.Send(&pb.GoodnightReply{Message: "Good night " + in.GetName() + "!"})
  	srv.Send(&pb.GoodnightReply{Message: "Good night " + in.GetName() + "!"})
  	srv.Send(&pb.GoodnightReply{Message: "Good night " + in.GetName() + "!"})
  	return nil
  }
  
  func main() {
  	lis, err := net.Listen("tcp", port)
  	if err != nil {
  		log.Fatalf("failed to listen: %v", err)
  	}
  	s := grpc.NewServer()
  	pb.RegisterGreeterServer(s, &server{})
  	if err := s.Serve(lis); err != nil {
  		log.Fatalf("failed to serve: %v", err)
  	}
  }
  
  

• greeter_client/main.go

  package main
  
  import (
  	"context"
  	"io"
  	"log"
  	"time"
  
  	pb "github.com/righ/grpc-go-example/goodnightworld/goodnightworld"
  	"google.golang.org/grpc"
  )
  
  const (
  	address = "grpc-server:50051"
  )
  
  func main() {
  	conn, err := grpc.Dial(address, grpc.WithInsecure(), grpc.WithBlock())
  	if err != nil {
  		log.Fatalf("did not connect: %v", err)
  	}
  	defer conn.Close()
  	c := pb.NewGreeterClient(conn)
  
  	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
  	defer cancel()
  
  	cli, err := c.SayGoodnight(ctx, &pb.GoodnightRequest{Name: "righ"})
  	if err != nil {
  		log.Fatalf("could not greet: %v", err)
  		return
  	}
  	for {
  		reply, err := cli.Recv()
  		if err == io.EOF {
  			break
  		}
  		if err != nil {
  			log.Fatalf("could not greet: %v", err)
  		}
  		log.Println(reply.Message)
  	}
  }