xDev Asia

REST、GraphQL、gRPC の詳細な比較: ユースケース、パフォーマンス、トレードオフ。 RESTful API のベストプラクティス、GraphQL スキーマ設計、プロトコルバッファーを使用した gRPC。 API のバージョン管理戦略と下位互換性。

マイクロサービスとマイクロフロントエンドのシステム設計 — 基本から運用まで

パート 2: マイクロサービスバックエンドの設計

xdev.asia

はじめに

API は、サービス間、およびバックエンドとフロントエンド間のコントラクトです。適切な API スタイルと適切な設計を選択することが、マイクロサービスアーキテクチャの成功か失敗かを決定します。この記事では、最も人気のある 3 つの API スタイルと、各ユースケースに適切な API スタイルを選択する手順について詳しく説明します。

1. REST API — デフォルトの選択

1.1 RESTful ベストプラクティス

リソースベースの URL:

GET    /api/v1/products              → List products
GET    /api/v1/products/{id}         → Get product
POST   /api/v1/products              → Create product
PUT    /api/v1/products/{id}         → Update product
PATCH  /api/v1/products/{id}         → Partial update
DELETE /api/v1/products/{id}         → Delete product
GET    /api/v1/products/{id}/reviews → Nested resource

ページネーション (カーソルベース):

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true,
    "total": 1500
  }
}

標準エラー応答:

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product with id '123' not found",
    "details": []
  }
}

1.2 API のバージョン管理戦略

戦略	例	長所	短所
URL パス	`/api/v1/products`	明示的でルーティングが簡単	URLの変更
ヘッダー	`Accept: application/vnd.api.v2+json`	クリーンな URL	非表示
クエリパラメータ	`/api/products?version=2`	シンプル	乱雑

推奨: URL パスのバージョン管理 — シンプル、明確、API ゲートウェイでのルーティングが簡単です。

1.3 REST を使用する場合

サードパーティ向けのパブリック API
シンプルなCRUD操作
クリティカルキャッシュ (HTTP ネイティブキャッシュ)
馴染みのあるチーム、成熟したツール

2. GraphQL — 柔軟なクエリ

2.1 マイクロフロントエンドに GraphQL を使用する理由

各マイクロフロントエンドには、同じサービスからの異なるデータが必要です。

# Product MFE (cần đầy đủ thông tin)
query ProductDetail {
  product(id: "123") {
    id, name, description, price
    images { url, alt }
    reviews { rating, comment, user { name } }
    relatedProducts { id, name, price }
  }
}

# Cart MFE (chỉ cần tên + giá)
query CartItem {
  product(id: "123") {
    id, name, price, thumbnail
  }
}

→ GraphQL は、オーバーフェッチ (REST が返す数が多すぎる) と アンダーフェッチ (REST が多くのエンドポイントを呼び出す必要がある) に対処します。

2.2 スキーマ設計のベストプラクティス

type Product {
  id: ID!
  name: String!
  slug: String!
  price: Money!
  images: [Image!]!
  category: Category!
  reviews(first: Int, after: String): ReviewConnection!
}

type Money {
  amount: Float!
  currency: Currency!
}

type ReviewConnection {
  edges: [ReviewEdge!]!
  pageInfo: PageInfo!
}

2.3 GraphQL を使用する場合

フロントエンドにはデータ取得の柔軟性が必要です
複数のフロントエンドクライアントが異なるデータを必要とする
BFF レイヤーまたは API ゲートウェイアグリゲーション
複雑な入れ子になったデータ関係

3. gRPC — 高性能内部

3.1 プロトコルバッファ

// product.proto
syntax = "proto3";

service ProductService {
  rpc GetProduct(GetProductRequest) returns (Product);
  rpc ListProducts(ListProductsRequest) returns (stream Product);
  rpc CreateProduct(CreateProductRequest) returns (Product);
}

message Product {
  string id = 1;
  string name = 2;
  double price = 3;
  repeated string image_urls = 4;
}

message GetProductRequest {
  string id = 1;
}

3.2 gRPC の利点

JSON シリアル化 (バイナリ形式) より ~10 倍高速
HTTP/2: 多重化、ヘッダー圧縮
強い型付け: 生成されたコード、コンパイル時チェック
双方向ストリーミング: リアルタイムデータフロー

3.3 gRPC を使用する場合

サービス間 通信 (内部のみ)
高スループット、低遅延の要件
ストリーミングデータ (リアルタイム更新、ログ)
Polyglot: Go、Java、Python、Node.js のコード生成

4. 意思決定マトリックス

基準	休憩	グラフQL	gRPC
主な用途	外部 API、CRUD	フロントエンドクエリ	サービス間
パフォーマンス	良い	良い	素晴らしい
キャッシング	HTTP ネイティブ	複雑な (永続的なクエリ)	マニュアル
学習曲線	低い	中	高
フロントエンドに優しい	はい	とても	いいえ (プロキシが必要)
ストリーミング	SSE/WebSocket	定期購読	ネイティブ
ツーリング	素晴らしい	良い	成長中
ブラウザのサポート	ネイティブ	ネイティブ	gRPC-Web が必要

4.1 電子商取引プラットフォームに関する推奨事項

Client → Shell/MFE:     GraphQL (flexible, typed)
MFE → BFF/Gateway:      REST hoặc GraphQL
Gateway → Services:      REST (simple CRUD) + gRPC (high-perf)
Service → Service:       gRPC (internal) + Events (async)

概要

REST: 外部 API と単純な CRUD のデフォルトの選択
GraphQL: マイクロフロントエンドに最適 — オーバーフェッチ/アンダーフェッチを軽減します
gRPC: サービス間の王様 — 高速、型付き、ストリーミング
実際: 正しい使用例には 3 つすべてを組み合わせて使用してください

次の記事: レッスン 6: サービス間通信 — 同期、非同期、およびイベント駆動型

レッスン 5: API 設計マスタークラス — REST、GraphQL、gRPC