{"canonical_url":"https://engineer.company/ja/glossary/grpc/","content_markdown":"# gRPC\n\n## どのようなものか\n\ngRPCは、遠隔手続き呼び出しのフレームワークです。プログラムは、別のマシンで動くサーバーを手元のオブジェクトのように扱い、メソッドを呼びます。gRPCが、HTTP/2上の独自プロトコルで呼び出しをネットワーク越しに運び、応答を戻り値として返します。\n\n出発点はサービス定義です。遠隔で実行する操作と、それぞれのリクエスト、応答の型を並べます。既定では、Googleのオープンソースのデータ直列化形式Protocol Buffersを使い、末尾が`.proto`のファイルへ書きます。言語やプラットフォームに依存しない形式です。ほかの形式も組み込めますが、指定しなければprotocol buffersを使います。コンパイラー`protoc`とgRPCプラグインがファイルを読み、両側のコードを生成します。クライアントには、サービスと同じメソッドを持つ手元のオブジェクト、スタブを作ります。単にクライアントと呼ぶ言語もあります。サーバー側には、実装すべきインターフェースを作ります。両側が一ファイルから生まれるため、Java製のサーバーが、Go、Python、Ruby製のクライアントへ答えられます。\n\nメソッドの形は四つあります。単項メソッドは、普通の関数のように、一つのリクエストから一つの応答を返します。サーバーストリーミングは、一つのリクエストへ応答のストリームを返し、クライアントストリーミングは、その逆です。双方向ストリーミングでは、両側が独立してストリームを送れます。一つの呼び出しの中では、送った順でメッセージが届くことをgRPCが保証します。\n\n通信にはHTTP/2を使います。各呼び出しは、完全修飾したサービス名とメソッド名からなるパスへの`POST`で、コンテンツ型は`application/grpc`です。各メッセージの前には五バイトの接頭部があり、一バイトが圧縮の有無、四バイトが長さを表します。呼び出しの結果は、HTTPの状態ではありません。gRPCが作る応答は、呼び出しが失敗しても状態200で、実際の結果は、本文の後に送るヘッダーフィールド、トレーラーに入ります。`grpc-status`が数値を持ち、必要に応じて`grpc-message`がエラーの説明を持ちます。\n\nこのためRESTとは性格が違います。REST APIは、リソースに名前を付け、HTTP自体のメソッドと状態コードで操作し、普通は誰でも読めるJSONの本文を使います。gRPC APIは、型付きのバイナリーメッセージを使うメソッドの一覧で、HTTP/2は下で運ぶ役目だけです。Protocol Buffersの文書もJSONと比較し、メッセージの小ささと処理の速さを強調します。\n\n## なぜ重要なのか\n\nまず契約があり、そこからコードが生まれます。多くのHTTP APIでは、APIの説明と、それを実装するコードが別にあり、ずれる場合があります。クライアントも、文書を読んで手で書くことがよくあります。gRPCでは、メソッドやフィールドの定義場所は`.proto`だけで、そこからすべてのクライアントとサーバーを生成します。メッセージを変えると、誰かが文書を読み直すのではなく、同じ生成ツールを通して、すべての言語へ伝わります。\n\nコンパクトに符号化できます。各フィールドを、名前ではなく、番号と値で送るためです。代償として、protocol buffersは自己記述形式ではないため、`.proto`なしには、完全には解釈できません。また、メッセージ全体が一度にメモリーへ収まることを前提とします。公式文書は、数メガバイトを超えるデータには、別の方法を勧めます。\n\nストリーミングは追加機能ではなく、設計の一部です。HTTP/2接続上のストリームとして呼び出すため、サーバーストリーミングのメソッドは、一度だけ答える呼び出しと同じ仕組みで、結果を送り続けられます。\n\n時間制限も呼び出しとともに伝わります。クライアントが期限を設定すると、gRPCが残り時間を`grpc-timeout`ヘッダーで送り、時間が尽きると、クライアントは`DEADLINE_EXCEEDED`を受け取り、サーバー側の呼び出しはキャンセルされます。サーバーがさらに別のサーバーを呼ぶとき、一部の実装は期限を引き継ぎます。JavaとGoは既定で行い、C++は有効化が必要です。期限を時刻ではなく残り時間として各区間へ渡すため、時計がずれるマシン同士でも、いつ諦めるかは一致します。\n\nエラーにも共通の語彙があります。gRPCは、0の`OK`から16の`UNAUTHENTICATED`まで、17の状態コードをプロトコル自体に定義します。そのためGoのクライアントとJavaのサーバーでも、`NOT_FOUND`や`UNAVAILABLE`の意味が一致します。\n\nどれも、同じチームや企業が両端を管理し、`.proto`を共有してビルドできる、サービス間の通信に適しています。ブラウザーには、それほど向きません。gRPCプロジェクトのプロトコル文書は、ブラウザーはスクリプトへHTTP/2のフレーミングを公開しておらず、今後もしないと記します。そのためブラウザーのコードは、gRPC-Webという別のプロトコルを使い、普通はプロキシーが通常のgRPCへ変換します。\n\n## 実際の活用例\n\n小さい請求サービスを示します。一つの単項メソッドが請求書を取得し、一つのサーバーストリーミングのメソッドが、顧客の請求書を一件ずつ送ります。\n\n```protobuf\nsyntax = \"proto3\";\n\npackage billing.v1;\n\nservice InvoiceService {\n  rpc GetInvoice(GetInvoiceRequest) returns (Invoice);\n  rpc WatchInvoices(WatchInvoicesRequest) returns (stream Invoice);\n}\n\nmessage GetInvoiceRequest {\n  string invoice_id = 1;\n}\n\nmessage WatchInvoicesRequest {\n  string customer_id = 1;\n}\n\nmessage Invoice {\n  reserved 4;\n  reserved \"discount_code\";\n  string invoice_id = 1;\n  string customer_id = 2;\n  int64 total_cents = 3;\n  string currency = 5;\n}\n```\n\n数値は既定値ではありません。フィールド番号で、通信中は名前の代わりに各フィールドを識別します。1から15は一バイトで符号化できるため、特によく設定するフィールドへ割り当てます。二つの`reserved`行は、かつて存在した、番号4、名前`discount_code`のフィールドを記録し、どちらも別のフィールドへ使い直せないようにします。\n\nPythonでは、一つのコマンドが、メッセージのクラスを持つ`billing_pb2.py`と、クライアントとサーバーのクラスを持つ`billing_pb2_grpc.py`を生成します。\n\n```sh\npython -m grpc_tools.protoc -Iprotos \\\n  --python_out=. --grpc_python_out=. protos/billing.proto\n```\n\n`GetInvoice`の一回の呼び出しは、HTTP/2のフレームでは次のようになります。\n\n```text\nHEADERS (flags = END_HEADERS)\n:method = POST\n:scheme = https\n:path = /billing.v1.InvoiceService/GetInvoice\n:authority = billing.example.com\nte = trailers\ncontent-type = application/grpc+proto\ngrpc-timeout = 2S\n\nDATA (flags = END_STREAM)\n\u003cLength-Prefixed Message\u003e\n\nHEADERS (flags = END_HEADERS)\n:status = 200\ncontent-type = application/grpc+proto\n\nDATA\n\u003cLength-Prefixed Message\u003e\n\nHEADERS (flags = END_STREAM, END_HEADERS)\ngrpc-status = 0\n```\n\n`2S`は二秒で、`te = trailers`は、gRPCと互換性のないプロキシーを検出するためです。請求書がなくても、応答の始まりは`:status = 200`で、最後のフレームに`grpc-status = 5`を入れ、`NOT_FOUND`を表します。`grpc-message`には、例えば`invoice not found`を添えます。すぐ失敗するサーバーは、メッセージをまったく付けず、状態を入れた一つの`HEADERS`フレームだけを返す場合もあります。\n\n一つの契約から両側を生成するのは、gRPCだけではありません。このサイトの[データベースを起点にAPI契約を生成した事例](/ja/portfolio/generated-the-api-contract-from-the-database-out/)は、OpenAPIで記述するAPIで行いました。流れはデータベースから外へ続きます。Goの型でAPIを定義し、HumaがOpenAPIの説明を生成し、そこから型付きのTypeScriptクライアントとモックハンドラーを作ります。フロントエンドの送るものとAPIの期待が一致しなくなれば、CIの契約検査がビルドを失敗させます。gRPCは、`.proto`を唯一のソースにして、同じ規律をツールチェーンへ組み込みます。\n\n## 問題が起きるところ\n\n**期限のない呼び出しが、いつまでも待ちます。** gRPCは既定で期限を設定しないため、応答が止まったサーバーを呼ぶクライアントは、事実上いつまでも応答を待ち続ける可能性があります。各呼び出しへ現実的な期限を付けてください。Pythonでは、秒単位の引数`timeout`です。\n\n```python\nimport grpc\n\nimport billing_pb2\nimport billing_pb2_grpc\n\ncredentials = grpc.ssl_channel_credentials()\nwith grpc.secure_channel(\"billing.example.com:443\", credentials) as channel:\n    stub = billing_pb2_grpc.InvoiceServiceStub(channel)\n    request = billing_pb2.GetInvoiceRequest(invoice_id=\"INV-1001\")\n    invoice = stub.GetInvoice(request, timeout=2.0)\n```\n\n時間が尽きると、`grpc.RpcError`が発生し、その`code()`が`grpc.StatusCode.DEADLINE_EXCEEDED`を返します。サーバー側では、期限を過ぎるとgRPCが`CANCELLED`で呼び出しをキャンセルします。ただし、ハンドラーが始めた仕事を止めるのは、サービス自身のコードの責任です。長く動くハンドラーは、キャンセルを調べ、自分で停止する必要があります。\n\n**タイムアウトしても、何も起きなかったとは限りません。** 成否はクライアントとサーバーが別々に決めるため、サーバーでは完了しても、クライアントでは`DEADLINE_EXCEEDED`で失敗する場合があります。キャンセルしても、済んだ仕事は元へ戻りません。単に再試行すると、同じ請求書を二度作る可能性があります。冪等であると明示しない限り、プロトコルはそう仮定しません。`UNAVAILABLE`は、一時的で、待ち時間を置いて再試行する価値がある可能性の最も高いコードです。ただし状態コードの文書は、冪等でない操作の再試行は、常に安全とは限らないと警告します。どのコードで再試行するかも、呼び出すコードの判断に任せています。\n\n**フィールド番号を再利用して、データを壊します。** メッセージ型を使い始めた後は、番号を変えられません。フィールドを消し、後で番号を別のものへ与えると、古いクライアントや保存したメッセージが、別の意味だったバイト列を、新しいフィールドとしてデコードします。Protocol Buffersのガイドは、解析エラー、個人データの漏えい、データ破損を挙げます。番号は決して振り直さず、上の例のように、削除した番号と名前をすべて予約してください。\n\n**HTTPからは、どの失敗も成功に見えます。** gRPCは失敗してもHTTP状態200を返すため、アクセスログや状態コードで作るエラー率など、HTTP状態だけで判断するものは、失敗を成功に数えます。仕様が、`application/grpc`でないコンテンツ型のリクエストへ415を返させるのも、ほかのHTTP/2クライアントに、gRPCのエラーを成功と読ませないためです。`grpc-status`を数え、`:status`で判断しないようにします。\n\n**長いストリームが、一台へ負荷を固定します。** 呼び出しは共有HTTP/2接続上のストリームで、一度始まると、別のサーバーへ移せません。何時間も続けば、その後いくらサーバーを増やしても、負荷は開始した場所に残ります。接続ごとに並行ストリーム数の上限もあり、達すると、終わるまで後の呼び出しがクライアントで待ちます。gRPCの性能ガイドは、性能や単純さの面で大きな利点がある場合だけストリーミングを使い、負荷の高い領域ごとに、別のチャネルを使うよう勧めます。\n\n**大きいデータが、一メッセージに収まりません。** gRPCは最大メッセージサイズを強制し、設定上限を超えると、送信側でも受信側でも`RESOURCE_EXHAUSTED`で失敗します。上限を上げても、問題が移るだけです。protocol buffersは全体がメモリーに収まることを前提とし、大きいデータでは、直列化したコピーがメモリー内に同時に複数存在する場合があります。小さいメッセージのストリームへ分けるか、gRPCの外で扱います。\n\n## 参考資料\n\n- [基本概念、構成、ライフサイクル](https://grpc.io/docs/what-is-grpc/core-concepts/)\n  — サービス定義、四つのメソッド、スタブ、期限、キャンセルです。\n- [HTTP2上のgRPC](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md)\n  — 通信プロトコルで、パス、ヘッダー、メッセージ接頭部、トレーラーの状態を説明します。\n- [状態コード](https://grpc.io/docs/guides/status-codes/) — 全17コードの意味と、ライブラリー自身が決して作らないコードです。\n- [期限](https://grpc.io/docs/guides/deadlines/) — 既定値がない理由、サーバーへの伝達方法、サービス間の引き継ぎです。\n- [言語ガイド：proto 3](https://protobuf.dev/programming-guides/proto3/) — フィールド番号、予約フィールド、メッセージ型を安全に変える規則です。\n\n\u003chttps://engineer.company/ja/glossary/grpc/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"一つの.protoファイルから、HTTP/2で通信するクライアントとサーバーを生成するgRPCを解説します。期限の伝播、型付きメッセージ、HTTPとは異なる状態コード、再試行やフィールド番号の問題も説明します。","formats":{"gemtext":"https://engineer.company/ja/glossary/grpc/index.gmi","gopher":"https://engineer.company/ja/glossary/grpc/gophermap","html":"https://engineer.company/ja/glossary/grpc/","json":"https://engineer.company/ja/glossary/grpc/index.json","markdown":"https://engineer.company/ja/glossary/grpc/index.md","pdf":"https://engineer.company/ja/glossary/grpc/index.pdf"},"kind":"page","language":"ja","title":"gRPCとは？","url":"https://engineer.company/ja/glossary/grpc/","version":1}