Go のマイクロサービス向けフレームワーク go-zero について学習します。

go-zero - Golang learning step 10-4

<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 > go-zero の学習を進めていきます。
<div class="img_wrap"><amp-img layout="responsive" src="/images/posts/315/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="#go-zero">go-zero</a></li>
<li><a href="#%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB">インストール</a></li>
<li><a href="#api-%E3%81%AE%E4%BD%9C%E6%88%90">API の作成</a></li>
<li><a href="#%E3%83%9F%E3%83%89%E3%83%AB%E3%82%A6%E3%82%A7%E3%82%A2">ミドルウェア</a>
<ol>
<li><a href="#%E3%83%9F%E3%83%89%E3%83%AB%E3%82%A6%E3%82%A7%E3%82%A2%E3%81%AE%E5%AE%9F%E8%A3%85">ミドルウェアの実装</a></li>
<li><a href="#%E5%8B%95%E4%BD%9C%E7%A2%BA%E8%AA%8D">動作確認</a></li>
</ol>
</li>
<li><a href="#grpc-%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%E6%A7%8B%E7%AF%89">gRPC サーバー構築</a>
<ol>
<li><a href="#etcd-%E3%81%AE%E8%A8%AD%E5%AE%9A%E3%81%A8%E7%9C%81%E7%95%A5%E6%96%B9%E6%B3%95">etcd の設定と省略方法</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://go-zero.dev/" rel="noopener noreferrer" target="_blank">[official] Go-zero</a></li>
<li><a href="https://github.com/zeromicro/go-zero" rel="noopener noreferrer" target="_blank">[OpenSource] Go-Zero</a></li>
<li><a href="https://app.daily.dev/tags/golang?ref=roadmapsh" rel="noopener noreferrer" target="_blank">[feed] Explore top posts about Golang</a></li>
</ul>
<h2 id="go-zero">go-zero</h2>
go-zero は、軽量で効率的な Go 向けの API フレームワーク です。
マイクロサービスの開発を簡単にし、パフォーマンスを最適化するための機能が組み込まれています。
<ul>
<li>高パフォーマンス：ゼロコストの RPC を実現する zrpc を採用。</li>
<li>シンプルなコード生成：goctl を使用して自動的に API コードを生成できる。</li>
<li>組み込みミドルウェア：認証やロギングなどが簡単に設定可能。</li>
<li>統合された RPC &#x26; REST API：REST と gRPC の両方をサポート。</li>
</ul>
<h2 id="インストール">インストール</h2>
プロジェクトの初期化
<pre><code class="hljs language-console">mkdir go_zero_sample
cd go_zero_sample
go mod init go_zero_sample
</code></pre>
go-zero では <code>goctl</code> コマンドを使ってファイル生成を行うためこれをインストールします。
<pre><code class="hljs language-console">go install github.com/zeromicro/go-zero/tools/goctl@latest
</code></pre>
go-zero をインストールします。
<pre><code class="hljs language-console">go get -u github.com/zeromicro/go-zero
</code></pre>
<h2 id="api-の作成">API の作成</h2>
<code>goctl</code> コマンドを使って API を作成します。
.api ファイル作成
<pre><code class="hljs language-console">goctl api -o user/user.api
</code></pre>
<code>goctl</code> コマンドで生成された <code>user/user.api</code> を編集してエンドポイントを定義します。
<pre><code class="hljs language-go">syntax = "v1"

type getUserRequest {
 UserId string `path:"userId"`
}

type getUserResponse {
 Message string `json:"message"`
}

service user-api {
 @handler GetUser
 get /users/id/:userId (getUserRequest) returns (getUserResponse)
}
</code></pre>
以下 <code>goctl</code> コマンドで Go のサーバーサイドコードを生成します。
<pre><code class="hljs language-console">goctl api go -api user/user.api -dir user
</code></pre>
以下ファイル群が生成されます。
<pre><code class="hljs language-console">user
├── etc
│ └── user-api.yaml
├── internal
│ ├── config
│ │ └── config.go
│ ├── handler
│ │ ├── getuserhandler.go
│ │ └── routes.go
│ ├── logic
│ │ └── getuserlogic.go
│ ├── svc
│ │ └── servicecontext.go
│ └── types
│ └── types.go
├── user.api
└── user.go
</code></pre>
<code>user/internal/logic/getuserlogic.go</code> に GetUser を実装します。
<pre><code class="hljs language-go">func (l *GetUserLogic) GetUser(req *types.GetUserRequest) (resp *types.GetUserResponse, err error) {
 return &#x26;types.GetUserResponse{
 Message: fmt.Sprintf("Hello World, UserId: %s", req.UserId),
 }, nil
}
</code></pre>
ここまでやるとエンドポイントが動作するので実際に確認してみます。
user-api サーバーを起動させます。
<pre><code class="hljs language-console">cd user
go mod tidy

go run user.go -f etc/user-api.yaml
</code></pre>
エンドポイントにリクエストを送信します。
<pre><code class="hljs language-console">curl -i http://localhost:8888/users/id/123
</code></pre>
レスポンス:
<pre><code class="hljs language-console">HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Traceparent: xxxxx
Date: Tue, 11 Feb 2025 23:53:03 GMT
Content-Length: 38

{"message":"Hello World, UserId: 123"}
</code></pre>
<h2 id="ミドルウェア">ミドルウェア</h2>
ミドルウェアは、リクエストとレスポンスの間に処理を挟む仕組みです。
例えば、以下のような処理を自動化できます。
<ul>
<li>ロギング（リクエストの記録）</li>
<li>認証（JWT の検証）</li>
<li>リクエストの前処理（ヘッダーの検査）</li>
<li>レスポンスの後処理（データの圧縮）</li>
</ul>
<h3 id="ミドルウェアの実装">ミドルウェアの実装</h3>
参考: <a href="https://go-zero.dev/en/docs/tutorials/api/middleware" rel="noopener noreferrer" target="_blank">https://go-zero.dev/en/docs/tutorials/api/middleware</a>
リクエストの開始時刻を記録し、処理が完了するまでにかかった時間（Duration）をログに出力するミドルウェア <code>RequestDurationLogger</code> を作成していきます。
<code>user/user.api</code> にミドルウェアを宣言します。
<pre><code class="hljs language-go">syntax = "v1"

type getUserRequest {
 UserId string `path:"userId"`
}

type getUserResponse {
 Message string `json:"message"`
}

// ミドルウェアを宣言
@server (
 middleware: RequestDurationLoggerMiddleware
)

service user-api {
 @handler GetUser
 get /users/id/:userId (getUserRequest) returns (getUserResponse)
}
</code></pre>
以下 <code>goctl</code> コマンドで Go のサーバーサイドコードを生成します。
<pre><code class="hljs language-console">goctl api go -api user/user.api -dir user
</code></pre>
<code>user/internal/middleware</code> に <code>requestdurationloggermiddleware.go</code> が生成されますので、<code>Handle</code> メソッドを実装していきます。
<pre><code class="hljs language-go">package middleware

import (
 "log"
 "net/http"
 "time"
)

type RequestDurationLoggerMiddleware struct {
}

func NewRequestDurationLoggerMiddleware() *RequestDurationLoggerMiddleware {
 return &#x26;RequestDurationLoggerMiddleware{}
}

func (m *RequestDurationLoggerMiddleware) Handle(next http.HandlerFunc) http.HandlerFunc {
 return func(w http.ResponseWriter, r *http.Request) {
 start := time.Now() // 処理開始時間を記録

 // 次のハンドラーを実行
 next(w, r)

 // 処理時間を計測
 duration := time.Since(start)

 // ログに出力
 log.Printf("[RequestDuration] %s %s took %v", r.Method, r.URL.Path, duration)
 }
}
</code></pre>
<ul>
<li><code>Handle</code> メソッドでリクエストを受け取る。</li>
<li><code>start := time.Now()</code> で開始時間を記録。</li>
<li><code>next(w, r)</code> を呼ぶことで、次の処理（API ハンドラー）にリクエストを渡す。</li>
<li><code>time.Since(start)</code> で処理時間を測定し、ログを出力。</li>
</ul>
<h3 id="動作確認">動作確認</h3>
user-api サーバーを起動し、ミドルウェア <code>RequestDurationLogger</code> の動作確認を行います。
<pre><code class="hljs language-console">cd user
go run user.go -f etc/user-api.yaml
</code></pre>
エンドポイントにリクエストを送信します。
<pre><code class="hljs language-console">curl -i http://localhost:8888/users/id/123
</code></pre>
以下が出力されるようになります。
<pre><code class="hljs language-console">2025/02/12 22:28:26 [RequestDuration] GET /users/id/123 took 466.709µs
</code></pre>
<h2 id="grpc-サーバー構築">gRPC サーバー構築</h2>
次は gRPC サーバーを構築してみます。
参考: <a href="https://go-zero.dev/en/docs/tutorials/grpc/server/example" rel="noopener noreferrer" target="_blank">https://go-zero.dev/en/docs/tutorials/grpc/server/example</a>
proto ファイルを生成します。
<pre><code class="hljs language-console">goctl rpc -o greet/greet.proto
</code></pre>
生成された proto ファイルは以下のようになっています。
<pre><code class="hljs language-proto">syntax = "proto3";

package greet;
option go_package="./greet";

message Request {
 string ping = 1;
}

message Response {
 string pong = 1;
}

service Greet {
 rpc Ping(Request) returns(Response);
}
</code></pre>
今回はこのままでいきます。
次に、この proto ファイルを元に Goサーバーサイドコードを生成します。
<pre><code class="hljs language-console">goctl rpc protoc greet/greet.proto --go_out=./greet --go-grpc_out=./greet --zrpc_out=./greet
</code></pre>
<code>greet/</code> 配下に以下ファイル群が生成されます。
<pre><code class="hljs language-console">greet
├── etc
│ └── greet.yaml
├── greet
│ ├── greet.pb.go
│ └── greet_grpc.pb.go
├── greet.go
├── greet.proto
├── greetclient
│ └── greet.go
└── internal
 ├── config
 │ └── config.go
 ├── logic
 │ └── pinglogic.go
 ├── server
 │ └── greetserver.go
 └── svc
 └── servicecontext.go
</code></pre>
<code>greet/internal/logic/pinglogic.go</code> の <code>Ping</code> メソッドを実装します。
<pre><code class="hljs language-go">func (l *PingLogic) Ping(in *greet.Request) (*greet.Response, error) {
 fmt.Printf("in %#v\n", in)
	return &#x26;greet.Response{
 Pong: "pong",
 }, nil
}
</code></pre>
gRPC Server Reflection を有効にするため、<code>greet/etc/greet.yaml</code> で開発モードを指定します。
<pre><code class="hljs language-yaml">Name: greet.rpc
ListenOn: 0.0.0.0:8080
Mode: dev # 追加
Etcd:
 Hosts:
 - 127.0.0.1:2379
 Key: greet.rpc
</code></pre>
gRPC サーバーを起動し、リクエストを送信します。
<pre><code class="hljs language-console"># 初回のみ
cd greet
go mod tidy

# gRPC サーバーを起動
go run greet.go -f etc/greet.yaml

# サービス一覧
grpcurl localhost:8080 list

greet.Greet
grpc.health.v1.Health
grpc.reflection.v1.ServerReflection


# メソッド一覧
grpcurl -plaintext localhost:8080 list greet.Greet

greet.Greet.Ping


# メソッドの詳細情報
grpcurl -plaintext localhost:8080 describe greet.Greet.Ping

greet.Greet.Ping is a method:
rpc Ping ( .greet.Request ) returns ( .greet.Response );


# 実際に gRPC リクエストを送信

grpcurl -plaintext localhost:8080 greet.Greet.Ping
{
 "pong": "pong"
}
</code></pre>
<h3 id="etcd-の設定と省略方法">etcd の設定と省略方法</h3>
<code>greet/etc/greet.yaml</code> にはデフォルトで etcd の設定が記述されています
<pre><code class="hljs language-yaml"># etcd の設定
Etcd:
 Hosts:
 - 127.0.0.1:2379
 Key: greet.rpc
</code></pre>
この設定が有効なままだと、gRPC サーバーの起動時に etcd への接続が求められます。
etcd がインストールされていないと、以下のようなエラーが発生します。
<pre><code class="hljs language-console">rpc error: code = DeadlineExceeded desc = latest balancer error: last connection error:
connection error: desc = "transport: Error while dialing: dial tcp 127.0.0.1:2379: connect: connection refused"
</code></pre>
<h4 id="etcd-をインストールする方法">etcd をインストールする方法</h4>
Mac の場合、Homebrew を使用して etcd をインストールできます。
<pre><code class="hljs language-console">brew install etcd
</code></pre>
<h4 id="etcd-を不要にする方法">etcd を不要にする方法</h4>
etcd なしで gRPC サーバーを起動する場合は、以下のように Hosts を空のリストにし、Key を "" に設定します。
<pre><code class="hljs language-yaml"># etcd を無効化する設定
Etcd:
 Hosts: []
 Key: ""
</code></pre>
この設定を適用すれば、etcd をインストールせずに gRPC サーバーを起動できます。
<h2 id="まとめ">まとめ</h2>
この記事では、Go のマイクロサービス向けフレームワーク <code>go-zero</code> の基本を学習しました。
<ul>
<li><code>goctl</code> を使用した API コードの自動生成</li>
<li><code>go-zero</code> による REST API の実装</li>
<li>ミドルウェアの導入方法</li>
<li>gRPC サーバーの構築手順
<ul>
<li><code>etcd</code> を使用したサービス管理とその省略方法</li>
</ul>
</li>
</ul>
go-zero のさらなる優秀な機能
<ul>
<li>モデル生成：SQL から Go のデータモデルを自動生成する <code>goctl model</code></li>
<li>タスクキュー：非同期処理を簡単に管理できる <code>queue</code> パッケージ</li>
<li>負荷分散：複数の RPC サーバー間でリクエストを分散処理</li>
<li>トレーシング：OpenTelemetry によるリクエストトレースのサポート</li>
<li>サービスリカバリ：クラッシュ時の自動回復機能</li>
<li>コンフィグ管理：環境変数や YAML による設定の柔軟な管理</li>
</ul>
<hr>
<hr>
[Next] <a href="/posts/316">Step 10-5: Watermill</a>
[Prev] <a href="/posts/314">Step 10-3: Micro</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 > go-zero の学習を進めていきます。
<div class="img_wrap"><img src="/images/posts/315/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="#go-zero">go-zero</a></li>
<li><a href="#%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB">インストール</a></li>
<li><a href="#api-%E3%81%AE%E4%BD%9C%E6%88%90">API の作成</a></li>
<li><a href="#%E3%83%9F%E3%83%89%E3%83%AB%E3%82%A6%E3%82%A7%E3%82%A2">ミドルウェア</a>
<ol>
<li><a href="#%E3%83%9F%E3%83%89%E3%83%AB%E3%82%A6%E3%82%A7%E3%82%A2%E3%81%AE%E5%AE%9F%E8%A3%85">ミドルウェアの実装</a></li>
<li><a href="#%E5%8B%95%E4%BD%9C%E7%A2%BA%E8%AA%8D">動作確認</a></li>
</ol>
</li>
<li><a href="#grpc-%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%E6%A7%8B%E7%AF%89">gRPC サーバー構築</a>
<ol>
<li><a href="#etcd-%E3%81%AE%E8%A8%AD%E5%AE%9A%E3%81%A8%E7%9C%81%E7%95%A5%E6%96%B9%E6%B3%95">etcd の設定と省略方法</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://go-zero.dev/" rel="noopener noreferrer" target="_blank">[official] Go-zero</a></li>
<li><a href="https://github.com/zeromicro/go-zero" rel="noopener noreferrer" target="_blank">[OpenSource] Go-Zero</a></li>
<li><a href="https://app.daily.dev/tags/golang?ref=roadmapsh" rel="noopener noreferrer" target="_blank">[feed] Explore top posts about Golang</a></li>
</ul>
<h2 id="go-zero">go-zero</h2>
go-zero は、軽量で効率的な Go 向けの API フレームワーク です。
マイクロサービスの開発を簡単にし、パフォーマンスを最適化するための機能が組み込まれています。
<ul>
<li>高パフォーマンス：ゼロコストの RPC を実現する zrpc を採用。</li>
<li>シンプルなコード生成：goctl を使用して自動的に API コードを生成できる。</li>
<li>組み込みミドルウェア：認証やロギングなどが簡単に設定可能。</li>
<li>統合された RPC &#x26; REST API：REST と gRPC の両方をサポート。</li>
</ul>
<h2 id="インストール">インストール</h2>
プロジェクトの初期化
<pre><code class="hljs language-console">mkdir go_zero_sample
cd go_zero_sample
go mod init go_zero_sample
</code></pre>
go-zero では <code>goctl</code> コマンドを使ってファイル生成を行うためこれをインストールします。
<pre><code class="hljs language-console">go install github.com/zeromicro/go-zero/tools/goctl@latest
</code></pre>
go-zero をインストールします。
<pre><code class="hljs language-console">go get -u github.com/zeromicro/go-zero
</code></pre>
<h2 id="api-の作成">API の作成</h2>
<code>goctl</code> コマンドを使って API を作成します。
.api ファイル作成
<pre><code class="hljs language-console">goctl api -o user/user.api
</code></pre>
<code>goctl</code> コマンドで生成された <code>user/user.api</code> を編集してエンドポイントを定義します。
<pre><code class="hljs language-go">syntax = "v1"

type getUserRequest {
 UserId string `path:"userId"`
}

type getUserResponse {
 Message string `json:"message"`
}

service user-api {
 @handler GetUser
 get /users/id/:userId (getUserRequest) returns (getUserResponse)
}
</code></pre>
以下 <code>goctl</code> コマンドで Go のサーバーサイドコードを生成します。
<pre><code class="hljs language-console">goctl api go -api user/user.api -dir user
</code></pre>
以下ファイル群が生成されます。
<pre><code class="hljs language-console">user
├── etc
│ └── user-api.yaml
├── internal
│ ├── config
│ │ └── config.go
│ ├── handler
│ │ ├── getuserhandler.go
│ │ └── routes.go
│ ├── logic
│ │ └── getuserlogic.go
│ ├── svc
│ │ └── servicecontext.go
│ └── types
│ └── types.go
├── user.api
└── user.go
</code></pre>
<code>user/internal/logic/getuserlogic.go</code> に GetUser を実装します。
<pre><code class="hljs language-go">func (l *GetUserLogic) GetUser(req *types.GetUserRequest) (resp *types.GetUserResponse, err error) {
 return &#x26;types.GetUserResponse{
 Message: fmt.Sprintf("Hello World, UserId: %s", req.UserId),
 }, nil
}
</code></pre>
ここまでやるとエンドポイントが動作するので実際に確認してみます。
user-api サーバーを起動させます。
<pre><code class="hljs language-console">cd user
go mod tidy

go run user.go -f etc/user-api.yaml
</code></pre>
エンドポイントにリクエストを送信します。
<pre><code class="hljs language-console">curl -i http://localhost:8888/users/id/123
</code></pre>
レスポンス:
<pre><code class="hljs language-console">HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Traceparent: xxxxx
Date: Tue, 11 Feb 2025 23:53:03 GMT
Content-Length: 38

{"message":"Hello World, UserId: 123"}
</code></pre>
<h2 id="ミドルウェア">ミドルウェア</h2>
ミドルウェアは、リクエストとレスポンスの間に処理を挟む仕組みです。
例えば、以下のような処理を自動化できます。
<ul>
<li>ロギング（リクエストの記録）</li>
<li>認証（JWT の検証）</li>
<li>リクエストの前処理（ヘッダーの検査）</li>
<li>レスポンスの後処理（データの圧縮）</li>
</ul>
<h3 id="ミドルウェアの実装">ミドルウェアの実装</h3>
参考: <a href="https://go-zero.dev/en/docs/tutorials/api/middleware" rel="noopener noreferrer" target="_blank">https://go-zero.dev/en/docs/tutorials/api/middleware</a>
リクエストの開始時刻を記録し、処理が完了するまでにかかった時間（Duration）をログに出力するミドルウェア <code>RequestDurationLogger</code> を作成していきます。
<code>user/user.api</code> にミドルウェアを宣言します。
<pre><code class="hljs language-go">syntax = "v1"

type getUserRequest {
 UserId string `path:"userId"`
}

type getUserResponse {
 Message string `json:"message"`
}

// ミドルウェアを宣言
@server (
 middleware: RequestDurationLoggerMiddleware
)

service user-api {
 @handler GetUser
 get /users/id/:userId (getUserRequest) returns (getUserResponse)
}
</code></pre>
以下 <code>goctl</code> コマンドで Go のサーバーサイドコードを生成します。
<pre><code class="hljs language-console">goctl api go -api user/user.api -dir user
</code></pre>
<code>user/internal/middleware</code> に <code>requestdurationloggermiddleware.go</code> が生成されますので、<code>Handle</code> メソッドを実装していきます。
<pre><code class="hljs language-go">package middleware

import (
 "log"
 "net/http"
 "time"
)

type RequestDurationLoggerMiddleware struct {
}

func NewRequestDurationLoggerMiddleware() *RequestDurationLoggerMiddleware {
 return &#x26;RequestDurationLoggerMiddleware{}
}

func (m *RequestDurationLoggerMiddleware) Handle(next http.HandlerFunc) http.HandlerFunc {
 return func(w http.ResponseWriter, r *http.Request) {
 start := time.Now() // 処理開始時間を記録

 // 次のハンドラーを実行
 next(w, r)

 // 処理時間を計測
 duration := time.Since(start)

 // ログに出力
 log.Printf("[RequestDuration] %s %s took %v", r.Method, r.URL.Path, duration)
 }
}
</code></pre>
<ul>
<li><code>Handle</code> メソッドでリクエストを受け取る。</li>
<li><code>start := time.Now()</code> で開始時間を記録。</li>
<li><code>next(w, r)</code> を呼ぶことで、次の処理（API ハンドラー）にリクエストを渡す。</li>
<li><code>time.Since(start)</code> で処理時間を測定し、ログを出力。</li>
</ul>
<h3 id="動作確認">動作確認</h3>
user-api サーバーを起動し、ミドルウェア <code>RequestDurationLogger</code> の動作確認を行います。
<pre><code class="hljs language-console">cd user
go run user.go -f etc/user-api.yaml
</code></pre>
エンドポイントにリクエストを送信します。
<pre><code class="hljs language-console">curl -i http://localhost:8888/users/id/123
</code></pre>
以下が出力されるようになります。
<pre><code class="hljs language-console">2025/02/12 22:28:26 [RequestDuration] GET /users/id/123 took 466.709µs
</code></pre>
<h2 id="grpc-サーバー構築">gRPC サーバー構築</h2>
次は gRPC サーバーを構築してみます。
参考: <a href="https://go-zero.dev/en/docs/tutorials/grpc/server/example" rel="noopener noreferrer" target="_blank">https://go-zero.dev/en/docs/tutorials/grpc/server/example</a>
proto ファイルを生成します。
<pre><code class="hljs language-console">goctl rpc -o greet/greet.proto
</code></pre>
生成された proto ファイルは以下のようになっています。
<pre><code class="hljs language-proto">syntax = "proto3";

package greet;
option go_package="./greet";

message Request {
 string ping = 1;
}

message Response {
 string pong = 1;
}

service Greet {
 rpc Ping(Request) returns(Response);
}
</code></pre>
今回はこのままでいきます。
次に、この proto ファイルを元に Goサーバーサイドコードを生成します。
<pre><code class="hljs language-console">goctl rpc protoc greet/greet.proto --go_out=./greet --go-grpc_out=./greet --zrpc_out=./greet
</code></pre>
<code>greet/</code> 配下に以下ファイル群が生成されます。
<pre><code class="hljs language-console">greet
├── etc
│ └── greet.yaml
├── greet
│ ├── greet.pb.go
│ └── greet_grpc.pb.go
├── greet.go
├── greet.proto
├── greetclient
│ └── greet.go
└── internal
 ├── config
 │ └── config.go
 ├── logic
 │ └── pinglogic.go
 ├── server
 │ └── greetserver.go
 └── svc
 └── servicecontext.go
</code></pre>
<code>greet/internal/logic/pinglogic.go</code> の <code>Ping</code> メソッドを実装します。
<pre><code class="hljs language-go">func (l *PingLogic) Ping(in *greet.Request) (*greet.Response, error) {
 fmt.Printf("in %#v\n", in)
	return &#x26;greet.Response{
 Pong: "pong",
 }, nil
}
</code></pre>
gRPC Server Reflection を有効にするため、<code>greet/etc/greet.yaml</code> で開発モードを指定します。
<pre><code class="hljs language-yaml">Name: greet.rpc
ListenOn: 0.0.0.0:8080
Mode: dev # 追加
Etcd:
 Hosts:
 - 127.0.0.1:2379
 Key: greet.rpc
</code></pre>
gRPC サーバーを起動し、リクエストを送信します。
<pre><code class="hljs language-console"># 初回のみ
cd greet
go mod tidy

# gRPC サーバーを起動
go run greet.go -f etc/greet.yaml

# サービス一覧
grpcurl localhost:8080 list

greet.Greet
grpc.health.v1.Health
grpc.reflection.v1.ServerReflection


# メソッド一覧
grpcurl -plaintext localhost:8080 list greet.Greet

greet.Greet.Ping


# メソッドの詳細情報
grpcurl -plaintext localhost:8080 describe greet.Greet.Ping

greet.Greet.Ping is a method:
rpc Ping ( .greet.Request ) returns ( .greet.Response );


# 実際に gRPC リクエストを送信

grpcurl -plaintext localhost:8080 greet.Greet.Ping
{
 "pong": "pong"
}
</code></pre>
<h3 id="etcd-の設定と省略方法">etcd の設定と省略方法</h3>
<code>greet/etc/greet.yaml</code> にはデフォルトで etcd の設定が記述されています
<pre><code class="hljs language-yaml"># etcd の設定
Etcd:
 Hosts:
 - 127.0.0.1:2379
 Key: greet.rpc
</code></pre>
この設定が有効なままだと、gRPC サーバーの起動時に etcd への接続が求められます。
etcd がインストールされていないと、以下のようなエラーが発生します。
<pre><code class="hljs language-console">rpc error: code = DeadlineExceeded desc = latest balancer error: last connection error:
connection error: desc = "transport: Error while dialing: dial tcp 127.0.0.1:2379: connect: connection refused"
</code></pre>
<h4 id="etcd-をインストールする方法">etcd をインストールする方法</h4>
Mac の場合、Homebrew を使用して etcd をインストールできます。
<pre><code class="hljs language-console">brew install etcd
</code></pre>
<h4 id="etcd-を不要にする方法">etcd を不要にする方法</h4>
etcd なしで gRPC サーバーを起動する場合は、以下のように Hosts を空のリストにし、Key を "" に設定します。
<pre><code class="hljs language-yaml"># etcd を無効化する設定
Etcd:
 Hosts: []
 Key: ""
</code></pre>
この設定を適用すれば、etcd をインストールせずに gRPC サーバーを起動できます。
<h2 id="まとめ">まとめ</h2>
この記事では、Go のマイクロサービス向けフレームワーク <code>go-zero</code> の基本を学習しました。
<ul>
<li><code>goctl</code> を使用した API コードの自動生成</li>
<li><code>go-zero</code> による REST API の実装</li>
<li>ミドルウェアの導入方法</li>
<li>gRPC サーバーの構築手順
<ul>
<li><code>etcd</code> を使用したサービス管理とその省略方法</li>
</ul>
</li>
</ul>
go-zero のさらなる優秀な機能
<ul>
<li>モデル生成：SQL から Go のデータモデルを自動生成する <code>goctl model</code></li>
<li>タスクキュー：非同期処理を簡単に管理できる <code>queue</code> パッケージ</li>
<li>負荷分散：複数の RPC サーバー間でリクエストを分散処理</li>
<li>トレーシング：OpenTelemetry によるリクエストトレースのサポート</li>
<li>サービスリカバリ：クラッシュ時の自動回復機能</li>
<li>コンフィグ管理：環境変数や YAML による設定の柔軟な管理</li>
</ul>
<hr>
<hr>
[Next] <a href="/posts/316">Step 10-5: Watermill</a>
[Prev] <a href="/posts/314">Step 10-3: Micro</a>

Author