Persona: あなたは Go 分散システムエンジニアです。正確性と運用性を備えた gRPC サービスを設計します — 適切なステータスコード、デッドライン、インターセプタ、グレースフルシャットダウンは、ハッピーパスと同じくらい重要です。

モード:

• ビルドモード — 新しい gRPC サーバーまたはクライアントをゼロから実装する
• レビューモード — 既存の gRPC コードを正確性、セキュリティ、運用性の問題について監査する

Go gRPC ベストプラクティス

gRPC は純粋なトランスポートレイヤーとして扱ってください — ビジネスロジックから分離してください。公式 Go 実装は google.golang.org/grpc です。

このスキルはすべてを網羅しているわけではありません。詳細についてはライブラリドキュメントとコード例を参照してください。Context7 は検索プラットフォームとして役立ちます。

クイックリファレンス

考慮事項	パッケージ / ツール
サービス定義	protoc または buf with .proto ファイル
コード生成	protoc-gen-go, protoc-gen-go-grpc
エラーハンドリング	google.golang.org/grpc/status with codes
リッチなエラー詳細	google.golang.org/genproto/googleapis/rpc/errdetails
インターセプタ	grpc.ChainUnaryInterceptor, grpc.ChainStreamInterceptor
ミドルウェアエコシステム	github.com/grpc-ecosystem/go-grpc-middleware
テスト	google.golang.org/grpc/test/bufconn
TLS / mTLS	google.golang.org/grpc/credentials
ヘルスチェック	google.golang.org/grpc/health

Proto ファイル構成

ドメインごとにバージョン付きディレクトリ (proto/user/v1/) で整理してください。常に Request/Response ラッパーメッセージを使用してください — string のような裸型は後でフィールドを追加することができません。buf generate または protoc でコード生成してください。

Proto とコード生成リファレンス

サーバー実装

• ヘルスチェックサービス (grpc_health_v1) を実装してください — Kubernetes プローブは準備状態の判定に必要です
• ロギング、認証、リカバリーなどのクロスカッティングの懸念事項にはインターセプタを使用してください — ビジネスロジックをクリーンに保ちます
• GracefulStop() とタイムアウトフォールバック Stop() を使用してください — インフライト RPC をドレインしながらハングアップを防ぎます
• プロダクションではリフレクションを無効にしてください — API 全体が露出します

srv := grpc.NewServer(
    grpc.ChainUnaryInterceptor(loggingInterceptor, recoveryInterceptor),
)
pb.RegisterUserServiceServer(srv, svc)
healthpb.RegisterHealthServer(srv, health.NewServer())

go srv.Serve(lis)

// On shutdown signal:
stopped := make(chan struct{})
go func() { srv.GracefulStop(); close(stopped) }()
select {
case <-stopped:
case <-time.After(15 * time.Second):
    srv.Stop()
}

インターセプタパターン

func loggingInterceptor(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
    start := time.Now()
    resp, err := handler(ctx, req)
    log.Printf("method=%s duration=%s code=%s", info.FullMethod, time.Since(start), status.Code(err))
    return resp, err
}

クライアント実装

• コネクションを再利用してください — gRPC は単一の HTTP/2 コネクション上で RPC を多重化します; リクエスト単位での接続は TCP/TLS ハンドシェイクを浪費します
• すべてのコールにデッドラインを設定してください (context.WithTimeout) — なければ、遅いアップストリームが goroutine を無期限にハングアップさせます
• Kubernetes ヘッドレスサービスで round_robin を dns:/// スキームで使用してください
• メタデータ (認証トークン、トレース ID) を metadata.NewOutgoingContext で渡してください

conn, err := grpc.NewClient("dns:///user-service:50051",
    grpc.WithTransportCredentials(creds),
    grpc.WithDefaultServiceConfig(`{
        "loadBalancingPolicy": "round_robin",
        "methodConfig": [{
            "name": [{"service": ""}],
            "timeout": "5s",
            "retryPolicy": {
                "maxAttempts": 3,
                "initialBackoff": "0.1s",
                "maxBackoff": "1s",
                "backoffMultiplier": 2,
                "retryableStatusCodes": ["UNAVAILABLE"]
            }
        }]
    }`),
)
client := pb.NewUserServiceClient(conn)

エラーハンドリング

常に status.Error で特定のコードを使用した gRPC エラーを返してください — 生の error は codes.Unknown になり、クライアントに処置可能な情報を伝えません。クライアントはコードを使用してリトライ vs フェイルファスト vs デグレードを判断します。

コード	使用時機
InvalidArgument	不正なフォーマットの入力 (フィールド欠落、形式が悪い)
NotFound	エンティティが存在しない
AlreadyExists	作成失敗、エンティティが既に存在
PermissionDenied	呼び出し元に権限がない
Unauthenticated	トークンが欠落または無効
FailedPrecondition	システムが必要な状態にない
ResourceExhausted	レート制限またはクォータ超過
Unavailable	一時的な問題、リトライは安全
Internal	予期しないバグ
DeadlineExceeded	タイムアウト

// ✗ 悪い例 — 呼び出し元は codes.Unknown を取得、リトライすべきか判断できない
return nil, fmt.Errorf("user not found")

// ✓ 良い例 — 特定のコードがクライアントに適切な対応を可能にする
if errors.Is(err, ErrNotFound) {
    return nil, status.Errorf(codes.NotFound, "user %q not found", req.UserId)
}
return nil, status.Errorf(codes.Internal, "lookup failed: %v", err)

フィールドレベルの検証エラーの場合、status.WithDetails で errdetails.BadRequest をアタッチしてください。

ストリーミング

パターン	ユースケース
サーバーストリーミング	サーバーが一連のデータを送信 (ログテイル、結果セット)
クライアントストリーミング	クライアントが一連のデータを送信、サーバーが一度に応答 (ファイルアップロード、バッチ)
双方向	両者が独立して送信 (チャット、リアルタイム同期)

大きな単一メッセージよりストリーミングを選択してください — メッセージごとのサイズ制限を避け、メモリプレッシャーを低減します。

func (s *server) ListUsers(req *pb.ListUsersRequest, stream pb.UserService_ListUsersServer) error {
    for _, u := range users {
        if err := stream.Send(u); err != nil {
            return err
        }
    }
    return nil
}

テスト

bufconn を使用して、ネットワークオーバーヘッドなしに完全な gRPC スタック (シリアライゼーション、インターセプタ、メタデータ) を演習するメモリ内コネクションを実現してください。常にエラーシナリオが期待される gRPC ステータスコードを返すことをテストしてください。

テストパターンと例

セキュリティ

• プロダクション環境では TLS を有効化する必要があります — 認証情報はメタデータで送信されます
• サービス間認証の場合、mTLS を使用するか、サービスメッシュ (Istio, Linkerd) に委譲してください
• ユーザー認証の場合、credentials.PerRPCCredentials を実装し、認証インターセプタでトークンを検証してください
• プロダクション環境では API 検出を防ぐためリフレクションを無効にすべきです

パフォーマンス

設定	目的	典型的な値
keepalive.ServerParameters.Time	アイドルコネクション用のピング間隔	30s
keepalive.ServerParameters.Timeout	ピング ACK タイムアウト	10s
grpc.MaxRecvMsgSize	大規模なペイロード用の 4 MB デフォルト上書き	16 MB
コネクションプーリング	高負荷ストリーミング用の複数コネクション	4 接続

ほとんどのサービスはコネクションプーリングが不要です — 複雑性を追加する前にプロファイリングしてください。

よくある間違い

間違い	修正方法
生の error を返す	codes.Unknown になり — クライアントはリトライすべきか判断できません。特定のコードで status.Errorf を使用してください
クライアントコールにデッドラインなし	遅いアップストリームが無期限にハングします。常に context.WithTimeout を使用してください
リクエストごとに新しいコネクション	TCP/TLS ハンドシェイクを浪費します。一度作成し再利用してください — HTTP/2 は RPC を多重化します
プロダクションでリフレクション有効	攻撃者がすべてのメソッドを列挙できます。開発/ステージング環境のみで有効化してください
すべてのエラーに codes.Internal を使用	間違ったコードはクライアントのリトライロジックを破壊します。Unavailable はリトライをトリガー; InvalidArgument はしません
RPC 引数として裸型を使用	string にフィールドを追加できません。ラッパーメッセージは下位互換性のある進化を可能にします
ヘルスチェックサービス欠落	Kubernetes が準備状態を判定できず、デプロイ中にポッドを削除します
コンテキストキャンセルを無視	長い操作が呼び出し元の放棄後も継続します。ctx.Err() をチェックしてください

相互参照

• → samber/cc-skills-golang@golang-context スキルを参照 (デッドラインとキャンセレーションパターン)
• → samber/cc-skills-golang@golang-error-handling スキルを参照 (gRPC エラーから Go エラーへのマッピング)
• → samber/cc-skills-golang@golang-observability スキルを参照 (gRPC インターセプタ: ロギング、トレース、メトリクス)
• → samber/cc-skills-golang@golang-testing スキルを参照 (bufconn を使用した gRPC テスト)