Go の gRPC-Gateway について学習します。

gRPC-Gateway - Golang learning step 10-1

<a href="https://roadmap.sh/" rel="noopener noreferrer" target="_blank">roadmap.sh</a> > <a href="https://roadmap.sh/golang" rel="noopener noreferrer" target="_blank">Go</a> > Tool for Microservices > gRPC-Gateway の学習を進めていきます。
<div class="img_wrap"><amp-img layout="responsive" src="/images/posts/312/01.png" width="1576" height="1146" alt="学習箇所"></div>
※ 学習メモとしての記録ですが、後にこのセクションを学ぶ道しるべとなるよう、ですます調で記載しています。
<h2 id="contents">contents</h2>
<ol>
<li><a href="#%E9%96%8B%E7%99%BA%E7%92%B0%E5%A2%83">開発環境</a></li>
<li><a href="#%E5%8F%82%E8%80%83-url">参考 URL</a></li>
<li><a href="#grpc-gateway">gRPC-Gateway</a></li>
<li><a href="#grpc-gateway-%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E3%81%A8%E6%BA%96%E5%82%99">gRPC-Gateway のインストールと準備</a>
<ol>
<li><a href="#1-%E5%BF%85%E8%A6%81%E3%81%AA%E3%83%84%E3%83%BC%E3%83%AB%E3%82%92%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB">1. 必要なツールをインストール</a></li>
<li><a href="#2-annotationsproto">2. annotations.proto</a></li>
<li><a href="#2-proto-%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90">2. .proto ファイルの作成</a></li>
<li><a href="#3-protoc-%E3%81%A7%E3%82%B3%E3%83%BC%E3%83%89%E7%94%9F%E6%88%90">3. protoc でコード生成</a></li>
</ol>
</li>
<li><a href="#grpc-%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%E3%81%AE%E5%AE%9F%E8%A3%85">gRPC サーバーの実装</a></li>
<li><a href="#grpc-gateway-%E3%81%AE%E5%AE%9F%E8%A3%85">gRPC-Gateway の実装</a></li>
<li><a href="#grpc--rest-api-%E3%81%AE%E5%8B%95%E4%BD%9C%E7%A2%BA%E8%AA%8D">gRPC &#x26; REST API の動作確認</a>
<ol>
<li><a href="#1-%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%E3%82%92%E8%B5%B7%E5%8B%95">1. サーバーを起動</a></li>
<li><a href="#2-%E5%8B%95%E4%BD%9C%E7%A2%BA%E8%AA%8D">2. 動作確認</a></li>
</ol>
</li>
</ol>
<h2 id="開発環境">開発環境</h2>
<ul>
<li>チップ: Apple M2 Pro</li>
<li>OS: macOS Sonoma</li>
<li>go version: go1.23.2 darwin/arm64</li>
</ul>
<h2 id="参考-url">参考 URL</h2>
<ul>
<li><a href="https://grpc-ecosystem.github.io/grpc-gateway/" rel="noopener noreferrer" target="_blank">[official] Grpc-gateway Doc</a></li>
<li><a href="https://github.com/grpc-ecosystem/grpc-gateway/" rel="noopener noreferrer" target="_blank">[OpenSource] Grpc-gateway</a></li>
<li><a href="https://app.daily.dev/onboarding" rel="noopener noreferrer" target="_blank">[feed] Explore top posts about gRPC</a></li>
</ul>
<h2 id="grpc-gateway">gRPC-Gateway</h2>
gRPC-Gateway は、gRPC サーバーの API を RESTful API として公開するためのツールです。
Go 言語で実装された gRPC サーバーを HTTP/JSON クライアントでも利用できるようにします。
これにより、gRPC クライアントが使えない環境でも gRPC サーバーと通信できる というメリットがあります。
gRPC-Gateway は以下の仕組みで動作します：
<ol>
<li><code>.proto</code> ファイルに gRPC の定義を記述</li>
<li>gRPC サーバーを実装（<code>grpc-go</code> を使用）</li>
<li><code>protoc</code>（Protocol Buffers コンパイラ）を使って gRPC-Gateway のコードを自動生成</li>
<li>生成したコードを用いて、REST API を提供する HTTP サーバーを起動</li>
</ol>
<h2 id="grpc-gateway-のインストールと準備">gRPC-Gateway のインストールと準備</h2>
<pre><code class="hljs language-sh"># プロジェクトを初期化
go mod init sample
</code></pre>
<h3 id="1-必要なツールをインストール">1. 必要なツールをインストール</h3>
まず、必要なツールやライブラリをインストールします。
<code>tools.go</code> を作成し、<code>go mod tidy</code> を実行します。
<pre><code class="hljs language-go">//go:build tools
// +build tools

package tools

import (
	_ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway"
	_ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2"
	_ "google.golang.org/grpc/cmd/protoc-gen-go-grpc"
	_ "google.golang.org/protobuf/cmd/protoc-gen-go"
)
</code></pre>
<h3 id="2-annotationsproto">2. annotations.proto</h3>
gRPC-Gateway では <code>google/api/annotations.proto</code> などの Google API 定義を利用するため、googleapis リポジトリをプロジェクトルートにダウンロードしておきます。
<pre><code class="hljs language-console">git clone https://github.com/googleapis/googleapis.git
</code></pre>
<h3 id="2-proto-ファイルの作成">2. .proto ファイルの作成</h3>
次に、<code>.proto</code> ファイルを作成します。<code>proto/hello.proto</code> を作成します。
<pre><code class="hljs language-proto">syntax = "proto3";

package hello;

option go_package = "grpc/hello";

import "google/api/annotations.proto";

service HelloService {
 rpc SayHello (HelloRequest) returns (HelloResponse) {
 option (google.api.http) = {
 post: "/v1/hello"
 body: "*"
 };
 }
}

message HelloRequest {
 string name = 1;
}

message HelloResponse {
 string message = 1;
}

</code></pre>
この <code>.proto</code> ファイルには SayHello という API を定義しています。
name を送信すると message が返る、シンプルな API です。
<h3 id="3-protoc-でコード生成">3. protoc でコード生成</h3>
以下のコマンドで gRPC と gRPC-Gateway のコードを自動生成します。
<pre><code class="hljs language-console">protoc -I . -I googleapis --go_out=. --go-grpc_out=. --grpc-gateway_out=. \
 --go_opt=paths=source_relative \
 --go-grpc_opt=paths=source_relative \
 --grpc-gateway_opt=paths=source_relative \
 proto/hello.proto
</code></pre>
<code>.proto</code> ファイルを <code>protoc</code> でコンパイルするときに、<code>import</code> された <code>.proto</code> ファイル（googleapis）を適切に解決するために <code>-I</code> オプション（<code>--proto_path</code>）を指定しています。
このコマンドを実行すると、以下の Go ファイルが生成されます：
<ul>
<li><code>proto/hello.pb.go</code>（gRPC メッセージ定義）</li>
<li><code>proto/hello_grpc.pb.go</code>（gRPC サーバーのインターフェース）</li>
<li><code>proto/hello.pb.gw.go</code>（gRPC-Gateway の変換コード）</li>
</ul>
<h2 id="grpc-サーバーの実装">gRPC サーバーの実装</h2>
次に、gRPC サーバーを作成します。
<code>server/main.go</code> を作成し、以下を実装します。
<pre><code class="hljs language-go">package main

import (
	"context"
	"fmt"
	"log"
	"net"

	"google.golang.org/grpc"
	"google.golang.org/grpc/reflection"
	pb "sample/proto"
)

// HelloService の実装
type helloServer struct {
	pb.UnimplementedHelloServiceServer
}

func (s *helloServer) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloResponse, error) {
	return &#x26;pb.HelloResponse{
		Message: fmt.Sprintf("Hello, %s!", req.Name),
	}, nil
}

func main() {
	// gRPC サーバーを起動
	listener, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatalf("Failed to listen: %v", err)
	}

	grpcServer := grpc.NewServer()
	reflection.Register(grpcServer)
	pb.RegisterHelloServiceServer(grpcServer, &#x26;helloServer{})

	log.Println("gRPC server listening on port 50051...")
	if err := grpcServer.Serve(listener); err != nil {
		log.Fatalf("Failed to serve: %v", err)
	}
}
</code></pre>
このコードでは SayHello メソッドを実装し、リクエストに対して <code>"Hello, &#x3C;name>!"</code> を返すシンプルな gRPC サーバーを作成しています。
<h2 id="grpc-gateway-の実装">gRPC-Gateway の実装</h2>
次に、gRPC サーバーを REST API として公開する gRPC-Gateway を実装します。
<code>gateway/main.go</code> を作成し、以下を実装します。
<pre><code class="hljs language-go">package main

import (
	"context"
	"log"
	"net/http"

	"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
	"google.golang.org/grpc"
	pb "sample/proto"
)

func main() {
	mux := runtime.NewServeMux()
	opts := []grpc.DialOption{grpc.WithInsecure()}

	// gRPC-Gateway を gRPC サーバーに接続
	err := pb.RegisterHelloServiceHandlerFromEndpoint(context.Background(), mux, "localhost:50051", opts)
	if err != nil {
		log.Fatalf("Failed to start gRPC-Gateway: %v", err)
	}

	log.Println("gRPC-Gateway listening on port 8080...")
	http.ListenAndServe(":8080", mux)
}
</code></pre>
このコードでは <code>RegisterHelloServiceHandlerFromEndpoint</code> を使い、gRPC サーバーの <code>localhost:50051</code> に接続し、REST API として公開しています。
<h2 id="grpc--rest-api-の動作確認">gRPC &#x26; REST API の動作確認</h2>
<h3 id="1-サーバーを起動">1. サーバーを起動</h3>
gRPC サーバーを起動します。
<pre><code class="hljs language-console">go run server/main.go
</code></pre>
gRPC-Gateway を起動します。
<pre><code class="hljs language-console">go run gateway/main.go
</code></pre>
<h3 id="2-動作確認">2. 動作確認</h3>
<h4 id="01-grpc-プロトコルでのリクエスト">01. gRPC プロトコルでのリクエスト</h4>
<a href="https://github.com/fullstorydev/grpcurl" rel="noopener noreferrer" target="_blank">grpcurl</a>（要インストール）を使って、サーバーに直接 gRPC プロトコルでリクエストを送信します。
<pre><code class="hljs language-console">grpcurl -plaintext -d '{"name": "Alice"}' localhost:50051 hello.HelloService/SayHello
</code></pre>
結果は以下になります。gRPC のバイナリ通信が適切に処理されていることが確認できました。
<pre><code class="hljs language-console">{
 "message": "Hello, Alice!"
}
</code></pre>
<h4 id="02-http-restful-api-でのリクエスト">02. HTTP (RESTful API) でのリクエスト</h4>
gRPC-Gateway 経由の REST API の動作確認です。<code>curl</code> コマンドを使ってリクエストを送信します。
<pre><code class="hljs language-console"> curl -X POST http://localhost:8080/v1/hello \
 -H "Content-Type: application/json" \
 -d '{"name": "Alice"}'
</code></pre>
以下、HTTP/JSON で gRPC-Gateway 経由のリクエストが成功し、REST API として正しく動作していることを確認できました。
<pre><code class="hljs language-console">{
 "message": "Hello, Alice!"
}
</code></pre>
<h2 id="まとめ">まとめ</h2>
gRPC-Gateway は、Go で実装した gRPC サーバーを、RESTful API（HTTP/JSON）として公開するためのツール。gRPC サーバーにアクセスできない環境（ブラウザや REST API クライアント）からでも、gRPC サーバーを利用できるようにする。
どんな時に役立つか
<ul>
<li>Web フロントエンドやモバイルアプリから gRPC サーバーを利用したい時
<ul>
<li>gRPC はバイナリ通信のため、通常のブラウザやモバイルから直接利用できないが、gRPC-Gateway を使えば REST API として利用可能になる。</li>
</ul>
</li>
<li>gRPC をサポートしていない外部サービスと連携する時
<ul>
<li>REST API しか使えない外部システムとも gRPC-Gateway を介して連携できる。</li>
</ul>
</li>
<li>gRPC サーバーを構築しつつ、従来の REST API も提供したい時
<ul>
<li>クライアントの移行をスムーズにしながら、新旧の API を共存させられる。</li>
</ul>
</li>
</ul>
gRPC-Gateway のメリット
<ul>
<li>gRPC の高性能な通信（バイナリ）と REST API の互換性を両立できる</li>
<li>gRPC サーバーのコードをそのまま活用しつつ、追加で REST API を提供できる</li>
<li>API の定義を <code>.proto</code> に統一することで、gRPC と REST API の一貫性を保てる</li>
<li>フロントエンドとバックエンドの技術スタックを柔軟に選べる</li>
</ul>
gRPC-Gateway のデメリット
<ul>
<li>gRPC-Gateway を経由すると、直接 gRPC を使うよりレイテンシが増加する</li>
<li>REST API のエラーハンドリングを適切に設定する必要がある</li>
</ul>
<hr>
<hr>
[Prev] <a href="/posts/313">Step 10-2: Rpcx</a>
[Prev] <a href="/posts/311">Step 9-1: Testing</a>

<a href="https://roadmap.sh/" rel="noopener noreferrer" target="_blank">roadmap.sh</a> > <a href="https://roadmap.sh/golang" rel="noopener noreferrer" target="_blank">Go</a> > Tool for Microservices > gRPC-Gateway の学習を進めていきます。
<div class="img_wrap"><img src="/images/posts/312/01.png" width="1576" height="1146" alt="学習箇所"></div>
※ 学習メモとしての記録ですが、後にこのセクションを学ぶ道しるべとなるよう、ですます調で記載しています。
<h2 id="contents">contents</h2>
<ol>
<li><a href="#%E9%96%8B%E7%99%BA%E7%92%B0%E5%A2%83">開発環境</a></li>
<li><a href="#%E5%8F%82%E8%80%83-url">参考 URL</a></li>
<li><a href="#grpc-gateway">gRPC-Gateway</a></li>
<li><a href="#grpc-gateway-%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E3%81%A8%E6%BA%96%E5%82%99">gRPC-Gateway のインストールと準備</a>
<ol>
<li><a href="#1-%E5%BF%85%E8%A6%81%E3%81%AA%E3%83%84%E3%83%BC%E3%83%AB%E3%82%92%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB">1. 必要なツールをインストール</a></li>
<li><a href="#2-annotationsproto">2. annotations.proto</a></li>
<li><a href="#2-proto-%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90">2. .proto ファイルの作成</a></li>
<li><a href="#3-protoc-%E3%81%A7%E3%82%B3%E3%83%BC%E3%83%89%E7%94%9F%E6%88%90">3. protoc でコード生成</a></li>
</ol>
</li>
<li><a href="#grpc-%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%E3%81%AE%E5%AE%9F%E8%A3%85">gRPC サーバーの実装</a></li>
<li><a href="#grpc-gateway-%E3%81%AE%E5%AE%9F%E8%A3%85">gRPC-Gateway の実装</a></li>
<li><a href="#grpc--rest-api-%E3%81%AE%E5%8B%95%E4%BD%9C%E7%A2%BA%E8%AA%8D">gRPC &#x26; REST API の動作確認</a>
<ol>
<li><a href="#1-%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%E3%82%92%E8%B5%B7%E5%8B%95">1. サーバーを起動</a></li>
<li><a href="#2-%E5%8B%95%E4%BD%9C%E7%A2%BA%E8%AA%8D">2. 動作確認</a></li>
</ol>
</li>
</ol>
<h2 id="開発環境">開発環境</h2>
<ul>
<li>チップ: Apple M2 Pro</li>
<li>OS: macOS Sonoma</li>
<li>go version: go1.23.2 darwin/arm64</li>
</ul>
<h2 id="参考-url">参考 URL</h2>
<ul>
<li><a href="https://grpc-ecosystem.github.io/grpc-gateway/" rel="noopener noreferrer" target="_blank">[official] Grpc-gateway Doc</a></li>
<li><a href="https://github.com/grpc-ecosystem/grpc-gateway/" rel="noopener noreferrer" target="_blank">[OpenSource] Grpc-gateway</a></li>
<li><a href="https://app.daily.dev/onboarding" rel="noopener noreferrer" target="_blank">[feed] Explore top posts about gRPC</a></li>
</ul>
<h2 id="grpc-gateway">gRPC-Gateway</h2>
gRPC-Gateway は、gRPC サーバーの API を RESTful API として公開するためのツールです。
Go 言語で実装された gRPC サーバーを HTTP/JSON クライアントでも利用できるようにします。
これにより、gRPC クライアントが使えない環境でも gRPC サーバーと通信できる というメリットがあります。
gRPC-Gateway は以下の仕組みで動作します：
<ol>
<li><code>.proto</code> ファイルに gRPC の定義を記述</li>
<li>gRPC サーバーを実装（<code>grpc-go</code> を使用）</li>
<li><code>protoc</code>（Protocol Buffers コンパイラ）を使って gRPC-Gateway のコードを自動生成</li>
<li>生成したコードを用いて、REST API を提供する HTTP サーバーを起動</li>
</ol>
<h2 id="grpc-gateway-のインストールと準備">gRPC-Gateway のインストールと準備</h2>
<pre><code class="hljs language-sh"># プロジェクトを初期化
go mod init sample
</code></pre>
<h3 id="1-必要なツールをインストール">1. 必要なツールをインストール</h3>
まず、必要なツールやライブラリをインストールします。
<code>tools.go</code> を作成し、<code>go mod tidy</code> を実行します。
<pre><code class="hljs language-go">//go:build tools
// +build tools

package tools

import (
	_ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway"
	_ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2"
	_ "google.golang.org/grpc/cmd/protoc-gen-go-grpc"
	_ "google.golang.org/protobuf/cmd/protoc-gen-go"
)
</code></pre>
<h3 id="2-annotationsproto">2. annotations.proto</h3>
gRPC-Gateway では <code>google/api/annotations.proto</code> などの Google API 定義を利用するため、googleapis リポジトリをプロジェクトルートにダウンロードしておきます。
<pre><code class="hljs language-console">git clone https://github.com/googleapis/googleapis.git
</code></pre>
<h3 id="2-proto-ファイルの作成">2. .proto ファイルの作成</h3>
次に、<code>.proto</code> ファイルを作成します。<code>proto/hello.proto</code> を作成します。
<pre><code class="hljs language-proto">syntax = "proto3";

package hello;

option go_package = "grpc/hello";

import "google/api/annotations.proto";

service HelloService {
 rpc SayHello (HelloRequest) returns (HelloResponse) {
 option (google.api.http) = {
 post: "/v1/hello"
 body: "*"
 };
 }
}

message HelloRequest {
 string name = 1;
}

message HelloResponse {
 string message = 1;
}

</code></pre>
この <code>.proto</code> ファイルには SayHello という API を定義しています。
name を送信すると message が返る、シンプルな API です。
<h3 id="3-protoc-でコード生成">3. protoc でコード生成</h3>
以下のコマンドで gRPC と gRPC-Gateway のコードを自動生成します。
<pre><code class="hljs language-console">protoc -I . -I googleapis --go_out=. --go-grpc_out=. --grpc-gateway_out=. \
 --go_opt=paths=source_relative \
 --go-grpc_opt=paths=source_relative \
 --grpc-gateway_opt=paths=source_relative \
 proto/hello.proto
</code></pre>
<code>.proto</code> ファイルを <code>protoc</code> でコンパイルするときに、<code>import</code> された <code>.proto</code> ファイル（googleapis）を適切に解決するために <code>-I</code> オプション（<code>--proto_path</code>）を指定しています。
このコマンドを実行すると、以下の Go ファイルが生成されます：
<ul>
<li><code>proto/hello.pb.go</code>（gRPC メッセージ定義）</li>
<li><code>proto/hello_grpc.pb.go</code>（gRPC サーバーのインターフェース）</li>
<li><code>proto/hello.pb.gw.go</code>（gRPC-Gateway の変換コード）</li>
</ul>
<h2 id="grpc-サーバーの実装">gRPC サーバーの実装</h2>
次に、gRPC サーバーを作成します。
<code>server/main.go</code> を作成し、以下を実装します。
<pre><code class="hljs language-go">package main

import (
	"context"
	"fmt"
	"log"
	"net"

	"google.golang.org/grpc"
	"google.golang.org/grpc/reflection"
	pb "sample/proto"
)

// HelloService の実装
type helloServer struct {
	pb.UnimplementedHelloServiceServer
}

func (s *helloServer) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloResponse, error) {
	return &#x26;pb.HelloResponse{
		Message: fmt.Sprintf("Hello, %s!", req.Name),
	}, nil
}

func main() {
	// gRPC サーバーを起動
	listener, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatalf("Failed to listen: %v", err)
	}

	grpcServer := grpc.NewServer()
	reflection.Register(grpcServer)
	pb.RegisterHelloServiceServer(grpcServer, &#x26;helloServer{})

	log.Println("gRPC server listening on port 50051...")
	if err := grpcServer.Serve(listener); err != nil {
		log.Fatalf("Failed to serve: %v", err)
	}
}
</code></pre>
このコードでは SayHello メソッドを実装し、リクエストに対して <code>"Hello, &#x3C;name>!"</code> を返すシンプルな gRPC サーバーを作成しています。
<h2 id="grpc-gateway-の実装">gRPC-Gateway の実装</h2>
次に、gRPC サーバーを REST API として公開する gRPC-Gateway を実装します。
<code>gateway/main.go</code> を作成し、以下を実装します。
<pre><code class="hljs language-go">package main

import (
	"context"
	"log"
	"net/http"

	"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
	"google.golang.org/grpc"
	pb "sample/proto"
)

func main() {
	mux := runtime.NewServeMux()
	opts := []grpc.DialOption{grpc.WithInsecure()}

	// gRPC-Gateway を gRPC サーバーに接続
	err := pb.RegisterHelloServiceHandlerFromEndpoint(context.Background(), mux, "localhost:50051", opts)
	if err != nil {
		log.Fatalf("Failed to start gRPC-Gateway: %v", err)
	}

	log.Println("gRPC-Gateway listening on port 8080...")
	http.ListenAndServe(":8080", mux)
}
</code></pre>
このコードでは <code>RegisterHelloServiceHandlerFromEndpoint</code> を使い、gRPC サーバーの <code>localhost:50051</code> に接続し、REST API として公開しています。
<h2 id="grpc--rest-api-の動作確認">gRPC &#x26; REST API の動作確認</h2>
<h3 id="1-サーバーを起動">1. サーバーを起動</h3>
gRPC サーバーを起動します。
<pre><code class="hljs language-console">go run server/main.go
</code></pre>
gRPC-Gateway を起動します。
<pre><code class="hljs language-console">go run gateway/main.go
</code></pre>
<h3 id="2-動作確認">2. 動作確認</h3>
<h4 id="01-grpc-プロトコルでのリクエスト">01. gRPC プロトコルでのリクエスト</h4>
<a href="https://github.com/fullstorydev/grpcurl" rel="noopener noreferrer" target="_blank">grpcurl</a>（要インストール）を使って、サーバーに直接 gRPC プロトコルでリクエストを送信します。
<pre><code class="hljs language-console">grpcurl -plaintext -d '{"name": "Alice"}' localhost:50051 hello.HelloService/SayHello
</code></pre>
結果は以下になります。gRPC のバイナリ通信が適切に処理されていることが確認できました。
<pre><code class="hljs language-console">{
 "message": "Hello, Alice!"
}
</code></pre>
<h4 id="02-http-restful-api-でのリクエスト">02. HTTP (RESTful API) でのリクエスト</h4>
gRPC-Gateway 経由の REST API の動作確認です。<code>curl</code> コマンドを使ってリクエストを送信します。
<pre><code class="hljs language-console"> curl -X POST http://localhost:8080/v1/hello \
 -H "Content-Type: application/json" \
 -d '{"name": "Alice"}'
</code></pre>
以下、HTTP/JSON で gRPC-Gateway 経由のリクエストが成功し、REST API として正しく動作していることを確認できました。
<pre><code class="hljs language-console">{
 "message": "Hello, Alice!"
}
</code></pre>
<h2 id="まとめ">まとめ</h2>
gRPC-Gateway は、Go で実装した gRPC サーバーを、RESTful API（HTTP/JSON）として公開するためのツール。gRPC サーバーにアクセスできない環境（ブラウザや REST API クライアント）からでも、gRPC サーバーを利用できるようにする。
どんな時に役立つか
<ul>
<li>Web フロントエンドやモバイルアプリから gRPC サーバーを利用したい時
<ul>
<li>gRPC はバイナリ通信のため、通常のブラウザやモバイルから直接利用できないが、gRPC-Gateway を使えば REST API として利用可能になる。</li>
</ul>
</li>
<li>gRPC をサポートしていない外部サービスと連携する時
<ul>
<li>REST API しか使えない外部システムとも gRPC-Gateway を介して連携できる。</li>
</ul>
</li>
<li>gRPC サーバーを構築しつつ、従来の REST API も提供したい時
<ul>
<li>クライアントの移行をスムーズにしながら、新旧の API を共存させられる。</li>
</ul>
</li>
</ul>
gRPC-Gateway のメリット
<ul>
<li>gRPC の高性能な通信（バイナリ）と REST API の互換性を両立できる</li>
<li>gRPC サーバーのコードをそのまま活用しつつ、追加で REST API を提供できる</li>
<li>API の定義を <code>.proto</code> に統一することで、gRPC と REST API の一貫性を保てる</li>
<li>フロントエンドとバックエンドの技術スタックを柔軟に選べる</li>
</ul>
gRPC-Gateway のデメリット
<ul>
<li>gRPC-Gateway を経由すると、直接 gRPC を使うよりレイテンシが増加する</li>
<li>REST API のエラーハンドリングを適切に設定する必要がある</li>
</ul>
<hr>
<hr>
[Prev] <a href="/posts/313">Step 10-2: Rpcx</a>
[Prev] <a href="/posts/311">Step 9-1: Testing</a>

Author