gRPCはcurlで叩けない — 関数を呼ぶようにAPIを呼ぶ

gRPC入門。二つのサーバーと仕様書、小さくまとまった通信の箱。

gRPCはcurlで叩けません。スキーマを先に決めて、関数を呼ぶようにAPIを呼ぶ方式です。RESTとの違いを実装して確かめます。

前回: 1画面のために3回叩く — GraphQLとRESTの違い 作業場所はVMの中(Ubuntu Server)です。ここまでで作った ~/server(Express + MySQL、/api/* と /graphql の両方が動いている状態)を、止めずにそのまま使います。

ここまでで、APIの作り方を2つ見ました。

  • REST — URLはモノ、メソッドが動詞
  • GraphQL — 1本のURLに、欲しい形を書いて投げる

3つ目があります。gRPC です。 そしてこの3つ目だけ、他の2つと前提がまるで違います。

先に、いちばん誤解しやすいところを書きます。

gRPC は、ブラウザから使うものではありません。 サーバーと、別のサーバーが話すための道具です。

RESTもGraphQLも、画面のためにありました。ブラウザが fetch で叩いて、JSONを受け取って、描く。読者が想像する「API」は、ほぼこれです。

gRPC が想定しているのは、そこではありません。

[ブラウザ] ──REST/GraphQL──> [入口のサーバー]
                                     │
                                     │ ここが gRPC
                                     ▼
                              [在庫サービス][課金サービス]

マイクロサービスの回で、「分けた瞬間に、関数呼び出しがネットワーク越しになる」という話をしました。その「ネットワーク越しになってしまった関数呼び出し」を、できるだけ関数呼び出しのように書き戻すための道具が gRPC です。

だから、この記事の結論も先に書いておきます。

いま作っている ~/server に gRPC は要りません。 でも、何をしている道具なのかは、触らないと絶対に分かりません。

対象レベル: 初級〜中級 / 区分: 必修

目次

この記事でわかること

  • gRPC はブラウザ向けではないこと。サービス同士が話すための道具で、REST/GraphQL とは競合していないこと
  • RPC は新しい考え方ではないこと。「ネットワークを隠して、関数呼び出しに見せる」という古い発想の、いまの形であること
  • Protocol Buffers が小さいのは、圧縮しているからではないこと。フィールド名を送らず、番号で送っているだけだということ。だから値が短いほど劇的に効き、日本語の長文では大して効かない
  • その代償が「人間が読めない」こと。curl で叩けず、ログに出しても意味が分からず、grpcurl のような専用の道具が要ること
  • 通信の形が4つあること。双方向ストリームは WebSocket と似て見えるが、目的が違うこと
  • ブラウザから直接は使えないこと。HTTP/2 のフレームを自分で触れないと成立しない設計だから
  • 外に出すAPIは REST のままでいいこと。個人のサービスに gRPC は要らないこと

この記事でやること

  1. ~/grpc-demo を新しく作る。 ~/server は止めない(別ポートで共存させる)
  2. .proto を書く。 実装より先に、型と番号を決める
  3. @grpc/grpc-js と @grpc/proto-loader でサーバーとクライアントを両方書いて、繋ぐ
  4. 同じデータを JSON と Protocol Buffers で符号化して、バイト数を実測して比べる
  5. curl で叩いてみて、失敗するのを見る。 そのうえで grpcurl を入れる

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
RPCRemote Procedure Call。離れた場所にある関数を、手元の関数のように呼ぶという考え方
gRPCGoogle が作った RPC の実装。HTTP/2 の上で動き、Protocol Buffers でデータを詰める
Protocol Buffers(protobuf)データをバイト列に詰める形式。JSON の代わり。人間には読めない
.proto ファイルどんなメソッドがあり、どんな型をやりとりするかを書く定義ファイル。これが仕様そのもの
スタブ(stub).proto から作られる呼び出し口。手元の関数のように見えるが、中身はネットワーク通信
シリアライズメモリ上のデータを、送れるバイト列に変換すること。逆がデシリアライズ
ストリーム1回の呼び出しの中で、何度もデータが流れる形。gRPC は標準で持っている
grpcurlgRPC 版の curl。curl では叩けないので、これが要る

「g」は Google の g ではありません(公式には毎リリース意味が変わる冗談になっています)。 覚えるべきは「RPC」のほうです。gRPC はRPC という古い考え方の、いちばん新しい実装にすぎません。

① RPC — 「ネットワークを隠す」という古い夢

gRPC を理解する近道は、Google から始めないことです。 この発想は1980年代からあります。

普通の関数呼び出しは、こう書きます。

const task = getTask(1);

これが同じマシンの中で動くなら、何も難しくありません。 ではこの関数が別のサーバーにあるとしたら。本来なら、こう書くことになります。

const res = await fetch("http://tasks.internal:3000/api/tasks/1");
const task = await res.json();

やりたいことは同じなのに、書くものが増えました。 URLを組み立て、メソッドを選び、JSONに直し、戻ってきたものをまたJSONから戻す。しかも型は誰も保証しません。

RPC の発想はこうです。 「その面倒を全部隠して、getTask(1) と書けるようにすればいいのでは?」

この夢は、何度も形を変えて実装されてきました。

時代名前どうなったか
1980年代Sun RPC / DCE RPCUNIX の内部で今も生きている(NFS など)
1990年代CORBA巨大で難解になり、廃れた
2000年前後SOAPXML で書いた RPC。 .wsdl に仕様を書き、そこからコードを生成する
2005年頃〜REST が主流に「関数を呼ぶな、モノを取れ」。SOAPの重さへの反動
2015年〜gRPCRPC の再来。 ただしHTTP/2 とバイナリで、SOAPの重さを捨てた

注目してほしいのは SOAP のところです。「仕様ファイルを先に書いて、そこからコードを生成する」というやり方は、gRPC の発明ではありません。 SOAP が .wsdl でやっていたことと、構造は同じです。

では、なぜ SOAP は嫌われて gRPC は使われているのか。 理由はほぼこの2つです。

  • SOAP は XML だった。 開始タグと終了タグで、同じ名前を2回送る。しかも人間が読める形にこだわった結果、巨大になった
  • SOAP は HTTP/1.1 の上で、毎回1往復していた。 gRPC はHTTP/2 で1本の接続を多重化する(HTTPキャッシュの回で名前だけ出た、あのHTTP/2です)

そして、RPC には昔から言われ続けている批判があります。 「ネットワークを隠すと、ネットワークの失敗まで隠れてしまう」。 手元の関数呼び出しは失敗しません。ネットワーク越しの呼び出しはタイムアウトし、途中で切れ、相手が落ちています。 getTask(1) に見せた瞬間、書いた人はそれを忘れます。 これは gRPC でも解決していません。書く側が覚えておくしかないものです。

② .proto を書く — スキーマが先

GraphQL の回で「実装より先にスキーマを書く」をやりました。 gRPC も同じです。というより、gRPC のほうが徹底しています。

GraphQL: スキーマを書かないと動かない gRPC: スキーマを書かないと、そもそもコードが存在しない

作業場所を作ります。~/server とは別のフォルダです。

bash
$ mkdir -p ~/grpc-demo
$ cd ~/grpc-demo
$ npm init -y
$ npm install @grpc/grpc-js @grpc/proto-loader mysql2

~/grpc-demo/tasks.proto を作ります。

syntax = "proto3";

package tasks;

service TaskService {
  rpc GetTask (GetTaskRequest) returns (Task);
  rpc ListTasks (ListTasksRequest) returns (stream Task);
}

message GetTaskRequest {
  int32 id = 1;
}

message ListTasksRequest {
  int32 limit = 1;
}

message Task {
  int32 id = 1;
  string title = 2;
  bool done = 3;
  int32 user_id = 4;
}

このファイルだけで、APIの仕様が全部書けています。 ドキュメントではありません。これがそのままコードになります。

service と rpc — URLが無い

注目してほしいのは、URLがどこにも無いことです。

rpc GetTask (GetTaskRequest) returns (Task);

「GetTask という関数がある。GetTaskRequest を渡すと Task が返る」。 これだけです。

  • REST なら GET /api/tasks/1 と考えるところ
  • GraphQL なら type Query { task(id: Int!): Task } と書くところ
  • gRPC は「関数の宣言」そのもの

「URLに動詞を入れるな」とRESTの回で散々やりました。 gRPC はその約束を、根本から採用していません。 GetTask も CreateTask も SendReminderMail も、全部ただの関数名です。

これは退化ではなく、前提の違いです。 REST は「不特定多数に公開するもの」として設計されました。だからHTTPの共通語彙(メソッド・ステータス・キャッシュ)に乗ることに価値がありました。 gRPC が話す相手は自分たちの別のサーバーです。共通語彙は要らない。速さと型が要る。

= 1 = 2 の番号は何なのか

ここが Protocol Buffers の心臓です。

message Task {
  int32 id = 1;
  string title = 2;
  bool done = 3;
  int32 user_id = 4;
}

= 1 は「初期値が1」ではありません。フィールド番号です。

送るときに、"title" という名前は送りません。代わりに 2 という番号を送ります。

これが後で実測するバイト数の差の、正体そのものです。そしてもう1つ、重要な性質が付いてきます。

やってよいことやってはいけないこと
フィールド名を変える(title → name)番号が同じなら通信は壊れない番号を変える。 古いクライアントが別の項目として読む
新しい項目を、新しい番号で足す(= 5)番号を使い回す。 消した = 3 を別の型で再利用すると、古い相手が黙って誤読する
使わなくなった番号を reserved 3; で封印する型を変える(int32 → string)

つまり番号は「互換性を保つための鍵」です。名前ではなく番号が本体なので、名前は自由に変えられる代わりに、番号は永久に固定になります。

エラーが出ないのが最悪なところです。 番号を使い回しても、送る側も受ける側も何も言いません。 数字は数字として読めてしまいます。壊れたことに気づくのは、データがおかしいと誰かが言い出したときです。

型の話

proto3 の型は素朴です。JSON より厳格で、SQL より緩いくらいだと思ってください。

.proto の型中身
int32 / int64整数。JavaScript では int64 が文字列で返ることがある(Number に収まらないため)
stringUTF-8 の文字列
bool真偽値
repeated Task tasks = 1;配列(repeated を付ける)
Task task = 1;入れ子(他の message をそのまま持てる)

proto3 には「値が無い」がありません。 送らなかった int32 は 0、string は ""、bool は false として読まれます。 「0 が入っている」と「未設定」が区別できません。 区別したいときは optional を付けるか、専用の型を使います。null を当たり前に使ってきた JSON との、いちばん大きな違いです。

③ サーバーを書く — コード生成を「動的読み込み」で省略する

gRPC の標準的なやり方は、.proto からコードを生成することです。 protoc というコンパイラを入れて、言語ごとのプラグインを入れて、生成コマンドを打つ。C++ や Go や Java では、これが普通です。

Node.js には、もっと楽な道があります。

@grpc/proto-loader は、実行時に .proto を読んで、その場でスタブを組み立てます。 生成ステップが要りません。

この記事ではこちらを使います。 覚えることが減り、.proto を直したら即座に反映されるので、学ぶには圧倒的に向いています。

本番では、生成するほうが有利な場面もあります。 型定義が手に入り、起動が速く、.proto の間違いをビルド時に見つけられるからです。やっていることは同じなので、必要になったときに切り替えれば済みます。

DBの接続情報は ~/server のものをそのまま使います。

bash
$ cp ~/server/.env ~/grpc-demo/.env
$ cut -d= -f1 ~/grpc-demo/.env
DB_HOST
DB_USER
DB_PASSWORD
DB_NAME
SESSION_SECRET

変数名は自分の .env に合わせてください。 下のコードは上の4つを前提に書いています。

~/grpc-demo/server.js を作ります。

const path = require("path");
const grpc = require("@grpc/grpc-js");
const protoLoader = require("@grpc/proto-loader");
const mysql = require("mysql2/promise");

// .proto を実行時に読む(コード生成をしない)
const packageDefinition = protoLoader.loadSync(
  path.join(__dirname, "tasks.proto"),
  { keepCase: false, longs: String, enums: String, defaults: true, oneofs: true }
);
const proto = grpc.loadPackageDefinition(packageDefinition).tasks;

const pool = mysql.createPool({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
});

// rpc GetTask に対応する関数
async function getTask(call, callback) {
  const [rows] = await pool.query(
    "SELECT id, title, done, user_id FROM tasks WHERE id = ?",
    [call.request.id]
  );
  if (rows.length === 0) {
    // HTTP の 404 に当たるもの。gRPC は独自のコード体系を持つ
    return callback({ code: grpc.status.NOT_FOUND, message: "そのタスクはありません" });
  }
  const r = rows[0];
  callback(null, { id: r.id, title: r.title, done: !!r.done, userId: r.user_id });
}

// rpc ListTasks は returns (stream Task) なので、何度も write する
async function listTasks(call) {
  const limit = call.request.limit || 10;
  const [rows] = await pool.query(
    "SELECT id, title, done, user_id FROM tasks ORDER BY id LIMIT ?",
    [limit]
  );
  for (const r of rows) {
    call.write({ id: r.id, title: r.title, done: !!r.done, userId: r.user_id });
  }
  call.end();
}

const server = new grpc.Server();
server.addService(proto.TaskService.service, { GetTask: getTask, ListTasks: listTasks });

server.bindAsync(
  "127.0.0.1:50051",
  grpc.ServerCredentials.createInsecure(),
  (err, port) => {
    if (err) throw err;
    console.log(`gRPC サーバーが ${port} 番で待っています`);
  }
);

見てほしいところが3つあります。

  1. app.get("/api/...") のようなルーティングがどこにも無い。 あるのは関数名と関数の対応表だけ({ GetTask: getTask })
  2. callback(null, {...}) で返す。 ステータスコードもヘッダーも書いていません。res.json() に当たるものが、ただのコールバックになっています
  3. createInsecure()。 gRPC は本来 TLS が前提です。暗号化なしは、明示的にこう書かないと選べません

動かします。

bash
$ cd ~/grpc-demo
$ node --env-file=.env server.js
gRPC サーバーが 50051 番で待っています

~/server(3000番)は止めていません。 「サーバーとは待ち続けるプログラム」の回でやったとおり、ポートが違えば別のプログラムが同時に待てます。 いま起きているのは、まさにマイクロサービスの回で説明した状態です。同じDBを見る、別プロセスが2つ。

④ クライアントを書いて、繋ぐ

gRPC は、クライアントも .proto から作ります。同じファイルからです。

~/grpc-demo/client.js を作ります。

const path = require("path");
const grpc = require("@grpc/grpc-js");
const protoLoader = require("@grpc/proto-loader");

const packageDefinition = protoLoader.loadSync(
  path.join(__dirname, "tasks.proto"),
  { keepCase: false, longs: String, enums: String, defaults: true, oneofs: true }
);
const proto = grpc.loadPackageDefinition(packageDefinition).tasks;

const client = new proto.TaskService(
  "127.0.0.1:50051",
  grpc.credentials.createInsecure()
);

// ① 単発の呼び出し
client.GetTask({ id: 1 }, (err, task) => {
  if (err) {
    console.error("失敗:", err.code, err.details);
  } else {
    console.log("1件:", task);
  }

  // ② サーバーストリーム
  const stream = client.ListTasks({ limit: 3 });
  stream.on("data", (t) => console.log("流れてきた:", t.title));
  stream.on("end", () => console.log("おわり"));
  stream.on("error", (e) => console.error("ストリーム失敗:", e.details));
});

別のターミナルから実行します。

bash
$ cd ~/grpc-demo
$ node client.js
1件: { id: 1, title: 'Linuxのコマンドを覚える', done: true, userId: 1 }
流れてきた: Linuxのコマンドを覚える
流れてきた: nginxを入れる
流れてきた: Dockerを触る
おわり

[スクリーンショット: 01_grpc_疎通.png] 左に node server.js、右に node client.js を並べたターミナルを撮ってください。右側に上のような出力が出ていることが条件です。

ここで起きたことを、はっきりさせておきます。

client.GetTask({ id: 1 }, (err, task) => { ... });

この1行の中で、実際には何が起きたか。

  1. { id: 1 } を Protocol Buffers のバイト列に詰めた
  2. HTTP/2 で POST /tasks.TaskService/GetTask を送った(内部的にはこういうパスです)
  3. 返ってきたバイト列を JavaScript のオブジェクトに戻した

全部、隠れています。 fetch も JSON.parse も書いていません。これが RPC の「関数呼び出しに見せる」です。

同時に、これが RPC の危うさです。 この1行はネットワークが死んでいれば失敗しますが、書いた見た目からは伝わりません。err を握りつぶすコードを書きたくなる誘惑が、REST より遥かに強いです。

⑤ バイト数を実測する

「gRPC は速い」「protobuf は小さい」は、あらゆる記事に書いてあります。 数字で確かめないと、何も分かりません。測ります。

~/grpc-demo/size.js を作ります。 protobufjs は @grpc/proto-loader が中で使っているので、追加インストールは要りません。

const path = require("path");
const protobuf = require("protobufjs");

const root = protobuf.loadSync(path.join(__dirname, "tasks.proto"));
const Task = root.lookupType("tasks.Task");

function compare(label, obj) {
  const json = Buffer.byteLength(JSON.stringify(obj), "utf8");
  const bin = Task.encode(Task.create(obj)).finish().length;
  const pct = Math.round((bin / json) * 100);
  console.log(`${label}: JSON ${json} バイト / protobuf ${bin} バイト (${pct}%)`);
}

compare("日本語のタイトル", { id: 1, title: "Linuxのコマンドを覚える", done: true, userId: 1 });
compare("短い英数のタイトル", { id: 1, title: "task-1", done: true, userId: 1 });
compare("タイトル無し", { id: 1, done: false, userId: 1 });
bash
$ node size.js
日本語のタイトル: JSON 74 バイト / protobuf 40 バイト (54%)
短い英数のタイトル: JSON 48 バイト / protobuf 14 バイト (29%)
タイトル無し: JSON 32 バイト / protobuf 4 バイト (13%)

[スクリーンショット: 02_バイト数比較.png] node size.js の出力を撮ってください。3行の数字が読めることが条件です。

なぜ小さいのか

ここを「圧縮しているから」と覚えると、後で必ず判断を間違えます。圧縮はしていません。

JSON はこう送ります。

{"id":1,"title":"task-1","done":true,"userId":1}

48バイトのうち、"id" "title" "done" "userId" という名前と、{ } " : , の記号で、34バイトを使っています。 実際のデータは 1 task-1 true 1 だけです。

protobuf はこう送ります(16進で表示しています)。

08 01 12 06 74 61 73 6b 2d 31 18 01 20 01

14バイト。読み方はこうです。

バイト意味
08フィールド番号 1、型は整数(番号と型が1バイトに詰まっている)
01その値。1
12フィールド番号 2、型は「長さ付きのデータ」
06長さ6バイト
74 61 73 6b 2d 31task-1
18 01フィールド番号 3 の値が 1(= true)
20 01フィールド番号 4 の値が 1

フィールド名が、どこにも入っていません。 "title" の代わりに 12 の中の「2」だけがあります。 これが全部です。 賢い圧縮も、辞書も、統計も使っていません。「名前を番号にした」だけで、半分以下になっています。

だから、効き方に偏りがある

3行の実測を、もう一度見てください。

中身削減なぜ
タイトル無し37 → 4 バイトほぼ名前しか送っていなかった。 しかも done: false title: "" は初期値なので1バイトも送らない
短い英数48 → 14 バイト名前の分がまるごと消える
日本語の長文74 → 40 バイト日本語1文字は UTF-8 で3バイト。 その部分は両方まったく同じ。減ったのは名前の分だけ

つまり「protobuf にすれば全部半分になる」ではありません。 効くのは「小さいデータを、たくさん、何度も送るとき」です。中身が大きい(画像・長文・添付)ほど、差は誤差に近づきます。 そして、これはまさに「サービス同士の通信」の形です。1件ずつの小さな問い合わせが、秒間何千回も飛ぶ。 gRPC が想定している場所そのものです。

代償 — 人間が読めない

上の14バイトを、もう一度見てください。

08 01 12 06 74 61 73 6b 2d 31 18 01 20 01

.proto ファイルが無ければ、これが何なのか誰にも分かりません。

これは、単に不便というだけの話ではありません。

  • ログに本文を出しても、読めません。 ログ集約の回でやったように文字列で grep する、が効きません
  • パケットを覗いても分かりません。 JSON なら目で読めたものが読めません
  • .proto を紛失したデータは、実質デコードできません。 番号しか無いので、何番が何だったのかを復元する手がかりがありません

「読めない」は、速さの副作用ではなく、速さの正体です。 名前を捨てたから小さいのであって、名前を捨てた以上、読めないのは当然です。両方は取れません。

⑥ curl で叩けない — そして grpcurl が要る

ここまで来ると、当然こう思います。「curl で叩いてみよう」。

やってみてください。 これがこの記事でいちばん体で覚えてほしいところです。

bash
$ curl -v http://127.0.0.1:50051/tasks.TaskService/GetTask
* Connected to 127.0.0.1 (127.0.0.1) port 50051
> GET /tasks.TaskService/GetTask HTTP/1.1
> Host: 127.0.0.1:50051
>
* Empty reply from server
* Connection died, tried 0 times before giving up
curl: (52) Empty reply from server

[スクリーンショット: 03_curlで叩けない.png] 上の curl -v を実行して失敗しているところを撮ってください。Empty reply from server が読めることが条件です。

POST にしても、JSON を付けても、同じです。

bash
$ curl -s -X POST http://127.0.0.1:50051/tasks.TaskService/GetTask \
    -H "Content-Type: application/grpc" -d '{"id":1}'

サーバーが落ちているわけではありません。 client.js は、いま動かしても普通に通ります。理由はこうです。

理由中身
HTTP/2 でしか話さないcurl は既定で HTTP/1.1 を話す。サーバーは「知らない言葉」として黙って切る
本文がバイナリ{"id":1} は protobuf ではない。手で書けない
本文の前に5バイトの枠があるgRPC は本文の先頭に「圧縮フラグ1バイト+長さ4バイト」を付ける。手で足すことになる
結果はトレーラーで返る成功・失敗は本文の後ろに付く grpc-status で返る。 ヘッダーではない

これが、運用でいちばん効いてくる不便さです。 障害のとき、REST なら curl 1行で「サーバーは生きているか」「このAPIは何を返すか」が分かります。 gRPC では、それが手元でできません。 道具を入れないと、何も確かめられません。

grpcurl を入れる

gRPC 版の curl があります。 公式ではありませんが、事実上の標準です。

リリースページで最新版の番号を確認してから、VMの中で実行します。

bash
$ cd /tmp
$ curl -sSL -o grpcurl.tar.gz https://github.com/fullstorydev/grpcurl/releases/download/v1.9.3/grpcurl_1.9.3_linux_x86_64.tar.gz
$ tar -xzf grpcurl.tar.gz grpcurl
$ sudo mv grpcurl /usr/local/bin/
$ grpcurl --version
grpcurl v1.9.3

叩きます。 .proto を渡すのがポイントです。

bash
$ cd ~/grpc-demo
$ grpcurl -plaintext -proto tasks.proto -d '{"id": 1}' \
    127.0.0.1:50051 tasks.TaskService/GetTask
{
  "id": 1,
  "title": "Linuxのコマンドを覚える",
  "done": true,
  "userId": 1
}

[スクリーンショット: 04_grpcurl.png] 上の grpcurl が JSON を返しているところを撮ってください。同じ端末の上のほうに、さっき失敗した curl が残っていると、対比になって分かりやすいです。

やっていることは、こうです。

  • -plaintext … TLSを使わない。 付けないと createInsecure() のサーバーには繋がりません
  • -proto tasks.proto … 仕様を教えてやる。 これが無いと grpcurl にも中身が分かりません
  • -d '{"id": 1}' … JSONで書いて、grpcurl が protobuf に直してくれる

-proto を渡さないと動かないことに注目してください。.proto を持っていない人は、そのAPIを叩けません。 RESTで言えば「URLを知らないと何もできない」より、遥かに強い制約です。

サーバー自身に喋らせる — リフレクション

毎回 .proto を持ち歩くのは現実的ではありません。 そこで サーバーリフレクションがあります。「お前はどんなメソッドを持っているのか」をサーバーに聞ける仕組みで、GraphQL のイントロスペクションと同じ発想です。

有効にすると、こう書けるようになります。

bash
$ grpcurl -plaintext 127.0.0.1:50051 list

有効にするかどうかは、判断が要ります。 GraphiQL を本番で開けてはいけないのと、まったく同じ理由です。繋がる人全員に、APIの全仕様を配ることになります。 社内ネットワークの中なら有効に、外に面しているなら無効に、が普通の落としどころです。

⑦ 通信の形は4つある

REST は「1回聞いて、1回返る」しかありません。 gRPC は4つ持っています。.proto の書き方だけで切り替わります。

service TaskService {
  // ① 単発(Unary)— RESTと同じ形
  rpc GetTask (GetTaskRequest) returns (Task);

  // ② サーバーストリーム — 1回聞いて、何度も返ってくる
  rpc ListTasks (ListTasksRequest) returns (stream Task);

  // ③ クライアントストリーム — 何度も送って、最後に1回返る
  rpc ImportTasks (stream Task) returns (ImportResult);

  // ④ 双方向ストリーム — 両方が好きなときに送る
  rpc Sync (stream Task) returns (stream Task);
}

stream という単語が、どちら側に付いているかだけの違いです。

形向き使いどころ
単発1 → 1ほとんどの呼び出し。まずこれで書く
サーバーストリーム1 → N大量の結果を、全部揃うのを待たずに流す。 100万件のエクスポート
クライアントストリームN → 1大量の送信を、1回の呼び出しにまとめる。 ログの一括アップロード
双方向N ↔ N片方が待たずに送りたいとき

双方向ストリームは、WebSocket と何が違うのか

見た目はそっくりです。 WebSocketの回でやった「両方が好きなときに送れる接続」と、同じことができます。違うのは、目的と前提です。

WebSocketgRPC 双方向ストリーム
想定する相手ブラウザ ↔ サーバーサーバー ↔ サーバー
送るものテキストかバイナリの塊。 中身の決まりは自分で作る.proto で型が決まっている
「どのメッセージが何か」自分で {"type":"chat"} のような仕組みを作る(WebSocketの回で実際にやりました)メソッドごとに接続が分かれているので、要らない
接続の寿命アプリが張りっぱなしにする。切れたら自分で貼り直す1回のメソッド呼び出しの間だけ。 終わったら閉じる
多重化1本の接続を、自分で使い分けるHTTP/2 が最初から多重化。10本同時でも接続は1本

いちばん大きいのは、真ん中の行です。 WebSocket で最初に自分で作ることになるのが「メッセージの種類と形の取り決め」でした。gRPC は、それが .proto として最初からあるということです。 逆に言えば、ブラウザが相手なら WebSocket のままで正しいです。次の節がその理由です。

⑧ ブラウザから直接は使えない

ここまでのクライアントは、全部 Node.js でした。 ブラウザの JavaScript から client.GetTask() はできません。

理由は、ライブラリが無いからではありません。原理的にできません。

ブラウザの JavaScript には、HTTP/2 のフレームを触る手段がありません。

fetch も XMLHttpRequest も、「リクエストを投げて、レスポンスを受け取る」までしか用意されていません。 gRPC が必要とするものは、その下にあります。

gRPC が必要とするものブラウザでできるか
HTTP/2 を明示的に使うできない。 HTTP/1.1 か HTTP/2 かはブラウザが勝手に決める
トレーラーを読む(grpc-status は本文の後ろに付く)できない。 fetch にトレーラーを読むAPIが無い
本文を送りながら、同時に受け取る(双方向)できない。 リクエスト本文を送りきってから応答を読む形しか無い
接続の張り方を制御するできない。 ブラウザが管理している

だから、間に翻訳役を置きます。これが gRPC-Web です。

[ブラウザ] ──gRPC-Web(HTTP/1.1でも通る形)──> [Envoy などのプロキシ] ──gRPC──> [サーバー]
  • ブラウザは、gRPC を少し崩した形(トレーラーを本文の中に埋め込む)で送る
  • プロキシが、それを本物の gRPC に直して後ろへ渡す
  • nginx のリバースプロキシでやったのと同じ位置に、もう1つ部品が増える

そして gRPC-Web には、いまも制限があります。 クライアントストリームと双方向ストリームは使えません(サーバーストリームまで)。 つまり、ブラウザ相手に「双方向」をやりたいなら、結局 WebSocket です。

これが「gRPC はブラウザ向けではない」の中身です。 使えないわけではありませんが、プロキシを1つ増やし、機能が減った状態で使うことになります。

⑨ どこで使うか — そして、どこで使わないか

ここまでの性質を並べると、答えは自然に出ます。

場面選ぶもの理由
不特定多数に公開するAPI✅ RESTcurl で叩ける。 ブラウザから直接使える。説明書が要らないくらい共通語彙がある
自社のフロントエンドが叩くAPI✅ REST か GraphQL画面ごとの都合に合わせやすい
社内のサービス同士✅ gRPC型がある。速い。多言語。 相手も自分たちなので .proto を共有できる
大量の小さな呼び出しが飛ぶところ✅ gRPC名前を送らない分が、回数ぶん効く
Go / Java / Python が混ざっている✅ gRPC.proto 1つから、全部の言語のクライアントが出る
個人が作っているサービス要らない下記

最後の行を、はっきり書きます。

いま作っている ~/server に gRPC を足す理由は、1つもありません。

  • サービスが1つしかありません。 マイクロサービスの回で確認したとおり、分けていないなら通信そのものが存在しません
  • 叩く相手はブラウザだけです。gRPC が一番不得意な相手です
  • curl が使えなくなる不便さを、1人で全部やる開発で背負う価値がありません
  • 速さで困っていません。 パフォーマンス改善の回でやったとおり、遅いのはたいていSQLで、シリアライズではありません

では、なぜ触ったのか。

  • 「スキーマを先に書く」が、GraphQL だけの話ではないと分かる(SOAP からずっと続いている)
  • JSON が「名前を毎回送っている」という、普段見えないコストが見える
  • curl で叩けることが、実はどれだけ大きな価値だったかが分かる
  • RPC の「ネットワークを隠す」が、便利さと危うさの両方であると体で分かる

この4つは、gRPC を使わない場面でも効きます。 それで十分です。

つまずいたところ

症状原因
curl が Empty reply from server正常です。 gRPC は HTTP/1.1 を話しません。サーバーは落ちていません
14 UNAVAILABLE: No connection establishedサーバーが起動していないか、アドレスが違う。 127.0.0.1:50051 にポート番号を書き忘れがち
クライアント側で task.user_id が undefinedkeepCase: false にすると user_id → userId に変換される。 .proto の名前とJSの名前がズレる。keepCase: true にすれば .proto のままになる
done が常に falseMySQLの BOOLEAN は TINYINT。 0 / 1 が返るので !!r.done で真偽値に直す(GraphQLの回とまったく同じ罠)
項目を1つ増やしたら、古いクライアントが変な値を読む番号を使い回した。 消した番号は reserved で封印する
grpcurl が Failed to dial target host-plaintext を忘れている。 既定でTLSを試すため
grpcurl が Symbol not found-proto を渡していないか、リフレクションが無効
int64 の値が文字列で返るJavaScript の Number に収まらないため。 longs: String の指定どおりの動作。バグではない
~/server が繋がらなくなった.env をコピーしたときに、元を上書きしていないか確認する(cp の向きに注意)

後片づけ

この回で作ったのは ~/grpc-demo という新しいフォルダと、grpcurl という実行ファイル1つだけです。~/server にも appdb にも、一切触っていません。

サーバーを止めます。

bash
$ # node server.js を動かしているターミナルで Ctrl+C

まるごと消すなら、こうです。

bash
$ rm -rf ~/grpc-demo
$ sudo rm /usr/local/bin/grpcurl

ポートが空いたことを確かめます。

bash
$ ss -ltnp | grep 50051

何も出なければ、止まっています。 ~/server のほうは確認しておきます。

bash
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/api/tasks

grpcurl は残しておいても害はありません。 ~/grpc-demo も、.env にDBのパスワードが入っている点だけ意識しておけば、残して構いません。

まとめ

  • gRPC はブラウザ向けではない。 サーバー同士が話すための道具で、REST や GraphQL と競合していない
  • RPC は「ネットワークを隠して、関数呼び出しに見せる」という1980年代からの発想。SOAP の .wsdl からコードを生成するやり方と、構造は同じ。gRPC は、それを HTTP/2 とバイナリでやり直したもの
  • 隠した副作用として、ネットワークの失敗まで隠れる。 getTask(1) に見えるものは、タイムアウトも切断もする
  • .proto を先に書く。 URLもメソッドも無く、あるのは関数の宣言だけ
  • = 1 は初期値ではなくフィールド番号。 名前は変えてよいが、番号は永久に固定。 使い回すとエラーも出ずに誤読される
  • @grpc/proto-loader を使えばコード生成が要らない。 .proto を実行時に読んで、その場でスタブが組み上がる
  • 実測: JSON 48 バイト → protobuf 14 バイト。 ただし日本語の長文では 74 → 40 にしかならない
  • 小さい理由は圧縮ではない。 "title" を送らず 2 を送っているだけ。だから値が短いほど効き、中身が大きいと差は消える
  • その代償が「人間が読めない」。 ログで grep できず、.proto が無ければ復元もできない。速さと可読性は両方取れない
  • curl で叩けない。 HTTP/2・バイナリ本文・5バイトの枠・トレーラーで返るステータス。grpcurl を入れて初めて確かめられる
  • 通信の形は4つ。 stream をどちら側に書くかだけで切り替わる
  • 双方向は WebSocket と似ているが、「メッセージの種類と形」を自分で決めなくていい点が違う。相手がブラウザなら WebSocket のままで正しい
  • ブラウザから直接は使えない。 HTTP/2 のフレームもトレーラーもブラウザから触れないため、gRPC-Web + プロキシが要る。しかも双方向は使えない
  • 社内のサービス同士には効く。外に出すAPIは REST。 そして個人のサービスに gRPC は要らない

参考リンク


次に読む

この記事は 【第5段階】バックエンドとデータベース の 24 / 29 本目です。

記事
← 前の記事1画面のために3回叩く — GraphQLとRESTの違い
→ 次の記事3つ目で言語の地図ができる — Pythonを触る

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Backend›APIs
  • gRPC(関数を呼ぶようにAPIを呼ぶ)
  • SOAP からの系譜と、REST・GraphQL との使い分け

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次