ドキュメント価格ブログ
お問い合わせ
ログイン無料で新規登録
Back to Tech Articles

Bridging gRPC and REST Automatically with gRPC-Gateway

10月 14, 2025
# Misc

Ethan Miller

Product Engineer · Leapcell

この記事はEnglish、日本語、한국어でも利用できます
Cover of "Bridging gRPC and REST Automatically with gRPC-Gateway"

Einführung

In modernen Microservice-Architekturen stellt die Wahl zwischen gRPC und REST oft ein Dilemma dar. gRPC hat sich mit seiner hohen Leistung, starken Typisierung und effizienten binären Serialisierung (Protocol Buffers) zum De-facto-Standard für die Inter-Service-Kommunikation innerhalb eines verteilten Systems entwickelt. Wenn es jedoch darum geht, Dienste für externe Clients wie Webbrowser, mobile Anwendungen oder Drittanbieter-Integratoren bereitzustellen, bleiben RESTful APIs aufgrund ihrer Einfachheit, ihrer weiten Verbreitung und ihrer exzellenten Tool-Unterstützung allgegenwärtig. Die manuelle Entwicklung und Wartung zweier separater APIs für denselben zugrunde liegenden Dienst – eine gRPC und eine REST – kann eine erhebliche Quelle für Komplexität, Redundanz und Entwicklungsaufwand sein. Hier glänzt gRPC-Gateway. Es bietet eine elegante Lösung, um Ihre gRPC-Dienste automatisch als idiomatische RESTful APIs bereitzustellen, sodass Sie die Stärken beider Paradigmen ohne die doppelte Implementierung belasten können. Dieser Artikel befasst sich damit, wie gRPC-Gateway diese nahtlose Integration erreicht und Entwicklern ermöglicht, effiziente, wartbare und hoch zugängliche Dienste zu erstellen.

Kernkonzepte und Implementierung

Bevor wir uns mit den Besonderheiten von gRPC-Gateway befassen, definieren wir kurz einige Kernkonzepte, die seiner Funktionsweise zugrunde liegen.

gRPC: Ein leistungsstarkes, Open-Source Universal RPC-Framework, das von Google entwickelt wurde. Es verwendet Protocol Buffers als seine Interface Definition Language (IDL) und für die Nachrichtenserialisierung sowie HTTP/2 für den Transport. Dies ermöglicht eine effiziente Kommunikation mit Funktionen wie Streaming, bidirektionalem Streaming und starker Typenprüfung.

Protocol Buffers (Protobuf): Ein sprachunabhängiger, plattformunabhängiger, erweiterbarer Mechanismus zur Serialisierung strukturierter Daten. Sie definieren Ihre Datenstruktur einmal und können dann generierten Quellcode verwenden, um Ihre strukturierten Daten einfach in und aus verschiedenen Datenströmen zu schreiben und zu lesen.

RESTful API: Ein architektonischer Stil für die Gestaltung vernetzter Anwendungen. Es basiert auf einem zustandslosen Client-Server-Kommunikationsmodell, verwendet Standard-HTTP-Methoden (GET, POST, PUT, DELETE) und gibt Ressourcenrepräsentationen zurück, typischerweise im JSON- oder XML-Format.

gRPC-Gateway: Ein Reverse-Proxy, der RESTful HTTP/JSON-Anfragen in gRPC-Anfragen übersetzt. Es liest eine gRPC-Dienstdefinition, einschließlich spezieller Annotationen (HTTP-Regeln), und generiert einen Reverse-Proxy-Server, der eingehende REST-Anfragen an den entsprechenden gRPC-Server weiterleitet. Der Schlüssel hier ist die "automatische Generierung", die den manuellen Codieraufwand erheblich reduziert.

Wie gRPC-Gateway funktioniert

Die Magie von gRPC-Gateway liegt in seiner Fähigkeit, Ihre Protobuf-Dienstdefinitionen zu introspektieren und Go-Code zu generieren, der als Brücke fungiert. Dieser Prozess umfasst in der Regel die folgenden Schritte:

  1. Definieren Sie Ihren gRPC-Dienst mit HTTP-Annotationen: Sie beginnen mit der Definition Ihrer Dienst- und Nachrichtenstrukturen unter Verwendung von Protocol Buffers. Für Methoden, die Sie als RESTful Endpunkte bereitstellen möchten, fügen Sie spezielle google.api.http-Optionen innerhalb der Protobuf-Definition hinzu. Diese Annotationen geben die HTTP-Methode (GET, POST usw.), den URL-Pfad und die Zuordnung von Anfrageparametern zu Protobuf-Feldern an.

  2. Generieren Sie gRPC- und gRPC-Gateway-Code: Mithilfe von protoc, dem Protocol Buffer Compiler, zusammen mit spezifischen Plugins (wie protoc-gen-go für gRPC und protoc-gen-grpc-gateway für das Gateway), generieren Sie den notwendigen Go-Code. Das Plugin protoc-gen-grpc-gateway erstellt für jeden Dienst eine Datei *.pb.gw.go, die die HTTP-Handler-Logik enthält.

  3. Führen Sie Ihren gRPC-Server aus: Ihr gRPC-Dienst implementiert die in Ihrer .proto-Datei definierten Logik und lauscht auf gRPC-Anfragen, typischerweise an einem bestimmten Port.

  4. Führen Sie den gRPC-Gateway-Proxy aus: Sie erstellen eine separate Go-Anwendung, die die generierten gRPC-Gateway-Handler instanziiert. Diese Gateway-Anwendung fungiert als HTTP-Server, der auf eingehende RESTful HTTP/JSON-Anfragen lauscht. Sie übersetzt dann diese Anfragen in gRPC-Aufrufe und leitet sie an Ihren gRPC-Server weiter. Die Antworten vom gRPC-Server werden dann wieder in JSON übersetzt und an den Client gesendet.

Code-Beispiel

Lassen Sie uns dies mit einem einfachen "Greeter"-Dienst veranschaulichen.

1. greeter.proto:

syntax = "proto3";

package greeter;

import "google/api/annotations.proto";

option go_package = "./greeter";

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloResponse) {
    option (google.api.http) = {
      get: "/v1/hello/{name}"
    };
  }

  rpc SayHelloPost (HelloRequest) returns (HelloResponse) {
    option (google.api.http) = {
      post: "/v1/hello_post"
      body: "*"
    };
  }
}

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

Beachten Sie die Zeilen option (google.api.http). Diese Annotationen sind entscheidend für gRPC-Gateway.

  • GET: "/v1/hello/{name}" ordnet eine GET-Anfrage an /v1/hello/John der Methode SayHello zu und extrahiert "John" in das Feld name von HelloRequest.
  • POST: "/v1/hello_post" mit body: "*" ordnet eine POST-Anfrage an /v1/hello_post mit einem JSON-Body wie {"name": "Alice"} der Methode SayHelloPost zu.

2. Go-Code generieren:

Sie benötigen den protoc-Compiler und die Plugins protoc-gen-go und protoc-gen-grpc-gateway, die installiert sind.

# protoc-gen-go installieren
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest # für die Generierung von gRPC-Diensten

# protoc-gen-grpc-gateway installieren
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest # optional, für die Generierung von OpenAPI-Spezifikationen

# Sicherstellen, dass Protobuf-Definitionen für Annotationen verfügbar sind
# Möglicherweise müssen Sie googleapis/google/api klonen oder kopieren und in Ihren Proto-Pfad einfügen
# Erstellen Sie z. B. einen Ordner 'google' in Ihrem Proto-Stammverzeichnis und fügen Sie 'api' darin ein.
# Oder verwenden Sie ein Tool wie 'buf' zur Verwaltung von Abhängigkeiten.

protoc -I. \
       -I/usr/local/include \
       -I$(go env GOPATH)/src \
       -I$(go env GOPATH)/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
       --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       --grpc-gateway_out=. --grpc-gateway_opt=paths=source_relative \
       greeter.proto

Dieser Befehl generiert greeter.pb.go (Protobuf-Nachrichten), greeter_grpc.pb.go (gRPC-Dienstschnittstelle und Client) und greeter.pb.gw.go (gRPC-Gateway-Handler).

3. Implementieren Sie den gRPC-Server (main.go für den Server):

package main

import (
	"context"
	"fmt"
	"log"
	"net"

	"google.golang.org/grpc"

	pb "your_module_path/greeter" // Ersetzen Sie your_module_path durch Ihren tatsächlichen Go-Modulpfad
)

type server struct {
	pb.UnimplementedGreeterServer
}

func (s *server) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloResponse, error) {
	log.Printf("Received: %v", in.GetName())
	return &pb.HelloResponse{Message: "Hello " + in.GetName()}, nil
}

func (s *server) SayHelloPost(ctx context.Context, in *pb.HelloRequest) (*pb.HelloResponse, error) {
	log.Printf("Received via POST: %v", in.GetName())
	return &pb.HelloResponse{Message: "Hello from POST, " + in.GetName()}, nil
}

func main() {
	lis, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatalf("failed to listen: %v", err)
	}
	s := grpc.NewServer()
	pb.RegisterGreeterServer(s, &server{})
	log.Printf("gRPC server listening at %v", lis.Addr())
	if err := s.Serve(lis); err != nil {
		log.Fatalf("failed to serve: %v", err)
	}
}

4. Führen Sie den gRPC-Gateway-Proxy aus (main.go für das Gateway, kann im selben oder in einem separaten Projekt sein):

package main

import (
	"context"
	"log"
	"net/http"

	"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"

	pb "your_module_path/greeter" // Ersetzen Sie your_module_path
)

func main() {
	ctx := context.Background()
	ctx, cancel := context.WithCancel(ctx)
	defer cancel()

	mux := runtime.NewServeMux()
	opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())} // Verwenden Sie mit grpc.WithTransportCredentials für die Produktion mit TLS

	// Greeter-Dienst registrieren
	err := pb.RegisterGreeterHandlerFromEndpoint(ctx, mux, ":50051", opts)
	if err != nil {
		log.Fatalf("Failed to register gateway: %v", err)
	}

	log.Printf("gRPC-Gateway server listening on :8080")
	if err := http.ListenAndServe(":8080", mux); err != nil {
		log.Fatalf("Failed to serve gateway: %v", err)
	}
}

Führen Sie nun den gRPC-Server und den Gateway-Server aus. Sie können dann RESTful-Anfragen stellen:

# GET-Anfrage
curl http://localhost:8080/v1/hello/World

# Erwartete Ausgabe: {"message":"Hello World"}

# POST-Anfrage
curl -X POST -H "Content-Type: application/json" -d '{"name": "Alice"}' http://localhost:8080/v1/hello_post

# Erwartete Ausgabe: {"message":"Hello from POST, Alice"}

Anwendungsszenarien

Der gRPC-Gateway ist in verschiedenen Szenarien besonders vorteilhaft:

  • Hybride Umgebungen: Wenn Sie interne gRPC-Dienste externen Clients zur Verfügung stellen müssen, die REST bevorzugen oder erfordern (z. B. Frontend-Webanwendungen, mobile Apps, Drittanbieter-APIs).
  • Schrittweise Migration: Wenn Sie eine bestehende RESTful API zu gRPC migrieren, ermöglicht gRPC-Gateway die Einführung von gRPC intern, während die Kompatibilität mit Ihren bestehenden externen Clients erhalten bleibt.
  • Vereinfachte Client-Entwicklung: Für Umgebungen, in denen native gRPC-Client-Bibliotheken nicht ohne Weiteres verfügbar sind oder komplex zu integrieren sind (z. B. Client-seitiges JavaScript, einfache Curl-Anfragen zum Testen).
  • API-Prototyping und -Dokumentation: Mit protoc-gen-openapiv2 kann gRPC-Gateway auch OpenAPI (Swagger)-Spezifikationen direkt aus Ihren Protobuf-Definitionen und HTTP-Annotationen generieren, was die API-Dokumentation vereinfacht.

Fazit

Der gRPC-Gateway bietet eine leistungsstarke und elegante Lösung für eine häufige architektonische Herausforderung: wie die Leistungsvorteile von gRPC für die interne Kommunikation mit der weiten Zugänglichkeit von REST für externe Clients in Einklang gebracht werden können. Durch die Nutzung von Protocol Buffer-Annotationen und Code-Generierung entfällt die Notwendigkeit einer manuellen Dual-API-Implementierung vollständig, wodurch erhebliche Entwicklungsbemühungen gespart und potenzielle Inkonsistenzen reduziert werden. Dieser Ansatz steigert nicht nur die Entwicklerproduktivität, sondern fördert auch eine konsistente Dienstdefinition in Ihrem gesamten System und ermöglicht es Ihnen so, die Vorteile von gRPC und REST wirklich voll auszuschöpfen.

Share this article

HackerNews

More Posts from Leapcell

Popular Posts