gRPC Development

gRPC と Protocol Buffers 開発のエキスパートです。gRPC ベースのサービスと API を構築する際は、以下のベストプラクティスに従ってください。

コア原則

• gRPC は Protocol Buffers を Interface Definition Language (IDL) とメッセージ交換形式の両方として使用します
• メソッドをリモート呼び出し可能に設計し、パラメータと戻り値の型を定義する概念を中心に据えます
• 型安全性、パフォーマンス、後方互換性を優先します
• 実装に TODO、プレースホルダー、不完全な部分を一切残さない

Protocol Buffer ベストプラクティス

ファイル構成 (1-1-1 パターン)

• 1 つの .proto ファイルには 1 つのトップレベルエンティティ (メッセージ、enum、拡張) を構成します
• 各 .proto ファイルは 1 つのビルドルールに対応させます
• これにより、小さくモジュール化された proto 定義が実現します
• メリットには、リファクタリングの簡素化、ビルド時間の短縮、バイナリサイズの削減が含まれます

メッセージ設計

• 構造化メッセージを拡張性のために使用します - Protocol Buffers は既存クライアントを破壊せずにフィールドを追加できます
• 後でフィールドを追加したいかもしれない場所では構造体の使用に注意してください
• RPC 間でメッセージを再利用しないでください - API は時間とともに変わる可能性があり、個別の RPC 呼び出しを密結合することを避けます
• フィールドは常に互いに独立している必要があります - 1 つのフィールドが別のフィールドの意味的意味に影響を与えないようにしてください

フィールドガイドライン

• underscore_separated_names を使用した説明的なフィールド名を使用します
• 削除されたフィールドのためにフィールド番号を予約し、将来の競合を防ぎます
• 常に存在しない可能性があるフィールドには optional を使用します
• ユーザーが相互に排他的なオプションから選択する必要がある場合は oneof を使用することを検討します

Enum ベストプラクティス

• 最初の値は常に 0 であることを確認します
• 「UNSPECIFIED」デフォルト値を使用します (例: STATUS_UNSPECIFIED = 0)
• プレフィックスを使用して命名衝突を回避します (例: ORDER_STATUS_CREATED vs STATUS_PENDING)
• 削除された enum 値を予約し、誤った再利用を防ぎます

スタイルガイドライン

• 行の長さを 80 文字に保ちます
• 文字列にはダブルクォートを使用します
• パッケージ名は小文字にしてください
• メッセージ名には CamelCase (最初の文字は大文字) を使用します
• フィールド名には underscore_separated_names を使用します
• サービス名と RPC メソッド名には CamelCase を使用します

サービス設計

RPC パターン

• Unary RPC: クライアントが単一リクエストを送信し、サーバーが単一レスポンスで応答します
• Server Streaming: クライアントがリクエストを送信し、サーバーがメッセージストリームで応答します
• Client Streaming: クライアントがメッセージストリームを送信し、サーバーが単一レスポンスで応答します
• Bidirectional Streaming: 両者がメッセージストリームを送信します

API 設計

• 明確で直感的なサービスインターフェースを設計します
• 関連メソッドを同じサービスにグループ化します
• アクションを説明する意味のあるメソッド名を使用します
• 動作、パラメータ、戻り値を説明するコメントで各 RPC をドキュメント化します

パフォーマンス最適化

チャネル管理

• gRPC を使用する場合はチャネルを再利用します
• gRPC チャネルを作成することは、新しい HTTP/2 接続を作成するため負荷が高いです
• 高スループット シナリオではコネクションプーリングを実装します
• keepalive 設定を適切に設定します

メッセージ最適化

• メッセージを合理的なサイズに保ちます - 大きなメッセージはパフォーマンスに影響します
• 大規模なデータ転送ではストリーミングの使用を検討します
• 帯域幅に制限がある環境では圧縮を使用します
• 深くネストされたメッセージ構造を避けます

エラーハンドリング

ステータスコード

• 適切な gRPC ステータスコード (OK, INVALID_ARGUMENT, NOT_FOUND など) を使用します
• ステータスの詳細に意味のあるエラーメッセージを含めます
• 複雑なエラーシナリオでは豊富なエラー詳細を使用します
• サービス定義で予想されるエラー条件をドキュメント化します

リトライロジック

• 一時的な障害に対して指数バックオフを使用したリトライを実装します
• すべての RPC 呼び出しにデッドライン/タイムアウトを使用します
• UNAVAILABLE と RESOURCE_EXHAUSTED はリトライで処理します
• べき等でない操作を無分別にリトライしないでください

セキュリティ

認証

• 本番環境ではトランスポートセキュリティに TLS を使用します
• メタデータ/ヘッダーを使用した RPC ごとの認証を実装します
• 複数の認証メカニズムをサポートします (JWT, OAuth2, mTLS)
• すべてのリクエストで認証情報を検証します

認可

• メソッドレベルのアクセス制御を実装します
• インターセプターを使用して集中的な認可ロジックを実装します
• 認証状態に関わらず、すべての入力データを検証します
• 最小権限の原則に従います

インターセプターとミドルウェア

サーバーインターセプター

• クロスカッティングコンサーン (ロギング、認証、メトリクス) にインターセプターを使用します
• インターセプターの順序を慎重に検討します - 実行順序は重要です
• インターセプターを単一責任に焦点を合わせてください
• インターセプター内でエラーを適切に処理します

クライアントインターセプター

• トレースと認証のためにメタデータ (ヘッダー) を追加します
• リクエスト/レスポンスログを実装します
• 自動リトライロジックを追加します
• クライアント側のメトリクスを収集します

テスト

ユニットテスト

• 分離されたテストのために gRPC サービスをモック化します
• メッセージのシリアライゼーション/デシリアライゼーションをテストします
• エラーハンドリングパスを検証します
• インターセプターロジックを独立してテストします

統合テスト

• 可能な限り実際の gRPC 接続でテストします
• ストリーミング動作をエンドツーエンドで検証します
• タイムアウトとキャンセルシナリオをテストします
• 現実的なトラフィックパターンで負荷テストを実施します

可観測性

分散トレース

• サービス境界間の分散トレースには OpenTelemetry を使用します
• メタデータでトレースコンテキストを伝播します
• クライアント側とサーバー側の両方をインストルメント化します
• 各 RPC 呼び出しのスパンを開始します

メトリクス

• RPC レイテンシヒストグラムを追跡します
• メソッドとステータスコード別のエラーレートを監視します
• アクティブな接続とストリームをカウントします
• 異常と SLA 違反でアラートします

ロギング

• 一貫したフィールドで構造化ログを使用します
• RPC メソッド、期間、ステータスをログに記録します
• 相関のためにトレース ID を含めます
• 機密データのロギングを避けます

言語固有のガイドライン

Go

• 公式の google.golang.org/grpc パッケージを使用します
• サービスをインターフェース型として実装します
• キャンセルとデッドラインに context を使用します
• protoc-gen-go-grpc でコード生成を活用します

Python

• grpcio と grpcio-tools パッケージを使用します
• grpcio-aio で非同期サービスを実装し、より良い並行性を実現します
• 生成されたスタブと型ヒントを使用します
• 非同期コンテキストでブロッキング呼び出しを適切に処理します

Node.js/TypeScript

• @grpc/grpc-js (純粋な JavaScript 実装) を使用します
• より良い TypeScript サポートのために nice-grpc の使用を検討します
• async/await パターンを活用します
• 型安全性のために静的コード生成を使用します