grpc-golang

gRPC Golang (gRPC-Go)

概要

Go で本番環境向けの gRPC サービスを設計、実装するための包括的なガイドです。Buf によるコントラクトの標準化、mTLS によるトランスポート層のセキュリティ、OpenTelemetry の計装による詳細な可観測性を扱います。

このスキルを使用する場合

• Go で gRPC を使ったマイクロサービス間通信を設計するとき。
• Protobuf を使用して高パフォーマンスな内部 API を構築するとき。
• ストリーミング処理（単方向または双方向）を実装するとき。
• Protobuf と Buf を使用して API コントラクトを標準化するとき。
• サービス間認証のために mTLS を設定するとき。

このスキルを使用しない場合

• gRPC の要件がない、REST/HTTP のみの公開 API を構築するとき。
• 新しい API バージョン（例：api.v2）を導入できず、後方互換性も確保できない状況で、レガシーな .proto ファイルを変更するとき。
• サービスメッシュのトラフィックルーティング（例：Istio/Linkerd）を管理するとき。これはアプリケーションコードの範囲外です。

ステップごとのガイド

1. 技術的なコンテキストを確認する：Go のバージョン、gRPC-Go のバージョン、プロジェクトで Buf と素の protoc のどちらを使用しているかを特定します。
2. 要件を確認する：mTLS の必要性、負荷パターン（単項／ストリーミング）、SLO、メッセージサイズの上限を特定します。
3. スキーマを計画する：パッケージのバージョン管理（例：api.v1）、リソースの種類、エラーのマッピングを定義します。
4. セキュリティを設計する：サービス間認証のために mTLS を実装します。
5. 可観測性を確保する：トレース、メトリクス、構造化ログのためにインターセプターを設定します。
6. 検証する：コード生成を確定する前に、必ず buf lint と破壊的変更のチェックを実行します。

詳しいパターン、コード例、アンチパターンについては、resources/implementation-playbook.md を参照してください。

例

例 1：サービスとメッセージの定義（v1 API）

syntax = "proto3";
package api.v1;
option go_package = "github.com/org/repo/gen/api/v1;apiv1";

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
}

message User {
  string id = 1;
  string name = 2;
}

message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}

ベストプラクティス

• ✅ 推奨： buf.yaml と buf.gen.yaml を使用して、ツールチェーンとリンティングを Buf で標準化します。
• ✅ 推奨： パッケージのパスでは常にセマンティックバージョニングを使用します（例：package api.v1）。
• ✅ 推奨： すべての内部サービス間通信で mTLS を必須にします。
• ✅ 推奨： リソースリークを防ぐため、すべてのストリーミングハンドラーで ctx.Done() を処理します。
• ✅ 推奨： ドメインエラーを標準の gRPC ステータスコード（例：codes.NotFound）にマッピングします。
• ❌ 非推奨： 生の内部エラー文字列やスタックトレースを gRPC クライアントに返します。
• ❌ 非推奨： リクエストごとに新しい grpc.ClientConn を作成します。接続は必ず再利用してください。

トラブルシューティング

• エラー：Gen の不整合：生成されたコードがスキーマと一致しない場合は、buf generate を実行し、go_package オプションを確認します。
• エラー：コンテキストの期限切れ：クライアントのタイムアウトを確認し、ストリーミングハンドラーでサーバーが無期限にブロックされないようにします。
• エラー：mTLS ハンドシェイク：クライアント側とサーバー側の両方で、CA 証明書が x509.CertPool に正しく追加されていることを確認します。

制限事項

• サービスメッシュのトラフィックルーティング（Istio/Linkerd の設定）は扱いません。
• gRPC-Web やブラウザベースの gRPC 統合は扱いません。
• バージョン固有の例を示すものであり、サポート対象バージョンの一覧ではありません。現在の Go/gRPC-Go モジュールの要件と API（例：grpc.Dial と grpc.NewClient）を確認してください。
• L7 の gRPC 対応ロードバランサーの設定（例：Envoy、NGINX）は扱いません。
• Buf lint の範囲を超える Protobuf スキーマレジストリや大規模なスキーマガバナンスは扱いません。

リソース

• 詳しいパターン、コード例、アンチパターンについては resources/implementation-playbook.md を参照してください。
• Google API 設計ガイド
• Buf ドキュメント
• gRPC-Go ドキュメント
• OpenTelemetry Go 計装

関連スキル

• @golang-pro - gRPC レイヤー以外の一般的な Go のパターンとパフォーマンス最適化。
• @go-concurrency-patterns - ストリーミングハンドラー向けの高度な goroutine ライフサイクル管理。
• @api-design-principles - .proto ファイルを作成する前のリソース命名とバージョニング戦略。
• @docker-expert - gRPC サービスのコンテナ化と、Docker secrets を介した TLS 証明書の注入設定。