Wenn Sie versucht haben, einen gRPC-Dienst von einem Browser aus aufzurufen, kennen Sie bereits die Schwierigkeiten. Browser können kein rohes gRPC sprechen, da sie HTTP-Trailer nicht steuern können. Daher müssen Sie einen Proxy wie Envoy hinzufügen, nur um den Datenverkehr zu übersetzen. ConnectRPC macht diesen Schritt überflüssig. Es ermöglicht Ihnen, Protobuf-basierte APIs zu erstellen, die ein Browser direkt aufrufen kann, die auf einen einfachen curl-Befehl reagieren und die weiterhin mit dem breiteren gRPC-Ökosystem zusammenarbeiten.
Dieser Leitfaden erklärt, was ConnectRPC ist, welches Problem das Connect-Protokoll löst, wie sich Connect im Vergleich zu gRPC, gRPC-Web und REST verhält und wie eine Connect-Anfrage über HTTP aussieht. Sie werden auch sehen, wie Connect- und gRPC-Endpunkte mit einem Standard-API-Client getestet und debuggt werden können.
Was ConnectRPC ist
ConnectRPC ist eine Familie von Bibliotheken zum Erstellen von Browser-kompatiblen und gRPC-kompatiblen HTTP-APIs aus Protocol Buffers. Sie definieren Ihren Dienst in einer .proto-Datei, generieren Code und implementieren Ihre Handler. Connect kümmert sich um Routing, Serialisierung, Komprimierung und Client-Generierung.
Das Projekt wurde von Buf, dem Unternehmen hinter den buf-Build-Tools für Protobuf, erstellt und ist nun ein Sandbox-Projekt der Cloud Native Computing Foundation (CNCF). Diese Herkunft ist wichtig: Connect wurde entwickelt, um in denselben Schema-First-Workflow zu passen, den Teams bereits mit buf und Protobuf verwenden.
Ein ConnectRPC-Server unterstützt drei Protokolle gleichzeitig:
- gRPC: vollständige Kompatibilität, einschließlich Streaming und Trailern.
- gRPC-Web: direkte Unterstützung, kein separater Proxy erforderlich.
- Connect: eigenes HTTP-basiertes Protokoll, optimiert für das Web.
Da ein einziger Server alle drei spricht, kann ein gRPC-Client einen Connect-Server aufrufen, und ein Connect-Client kann jeden gRPC-Server aufrufen. Sie wählen das Protokoll pro Client, oft mit einer einzigen Konfigurationsänderung und ohne Code-Umschreibung.
Das Problem, das Connect löst
gRPC ist schnell und stark typisiert, aber es geht von Annahmen aus, die das Web nicht einhält. Es basiert auf HTTP/2 und HTTP-Trailern, um Statusinformationen zu übertragen. Browser stellen JavaScript keine Trailer zur Verfügung, sodass ein Browser nicht als nativer gRPC-Client fungieren kann. Der übliche Workaround ist gRPC-Web plus ein übersetzender Proxy wie Envoy, der zwischen dem Browser und Ihrem gRPC-Backend sitzt.
Das funktioniert, aber es fügt bewegliche Teile hinzu. Sie betreiben und konfigurieren nun einen Proxy und debuggen einen zusätzlichen Schritt. Für Teams, die typisierte APIs und Browserzugriff ohne diesen Overhead wünschen, fühlt sich die Einrichtung schwerfälliger an, als sie sein sollte.
Connect geht einen anderen Weg. Sein eigenes Protokoll läuft über Standard-HTTP, sodass ein Browser es direkt aufrufen kann und Sie keinen Proxy für den Browser-Datenverkehr benötigen. Wenn Sie auch bestehende gRPC-Clients bedienen müssen, übernimmt derselbe Connect-Server auch diese. Sie erhalten ein einziges Backend, das Browser, Kommandozeilen-Tools und gRPC-Dienste gleichermaßen bedient.
Connect vs. gRPC vs. gRPC-Web vs. REST
Diese vier Ansätze überschneiden sich, daher ist es hilfreich, sie gegenüberzustellen.
gRPC verwendet Protobuf über HTTP/2 mit binärer Rahmung und Trailern. Es ist effizient und unterstützt alle vier Streaming-Modi, ist aber umständlich von einem Browser oder einer Shell aus aufzurufen. Wenn Sie Ihr Wissen über die Transportschicht auffrischen möchten, lesen Sie wie gRPC und HTTP/2 zusammenarbeiten.
gRPC-Web ist eine browserfreundliche Variante von gRPC. Es konzentriert sich immer noch auf Protobuf und benötigt normalerweise einen Proxy, um eine Brücke zu einem echten gRPC-Backend zu schlagen. Unser Leitfaden zu was gRPC-Web ist behandelt, wo es passt.
Connect behält das Protobuf-Schema und das gRPC-ähnliche Methodenmodell bei, aber sein Protokoll läuft sauber über HTTP/1.1, HTTP/2 und HTTP/3. Unäre Aufrufe transportieren einen einfachen JSON- oder Protobuf-Body ohne gRPC-binäre Rahmung, und Antworten verwenden echte HTTP-Statuscodes. Diese Kombination macht einen Connect-Aufruf so zugänglich wie jeden REST-Aufruf.
REST ist ressourcenorientiert und schema-optional. Es ist der am universellsten unterstützte Stil, aber es fehlen die Codegenerierung und die strikte Typisierung, die Protobuf bietet. Wenn Sie die Kompromisse abwägen, erklärt gRPC vs. REST die Unterschiede.
Kurz gesagt: Connect zielt darauf ab, Ihnen die Typisierung und das Tooling von gRPC mit der Reichweite und Debugbarkeit von REST zu bieten. Es stützt sich auf Protobuf und das Methodenmodell von gRPC, während es die Teile weglässt, die Browser und Shells nicht verarbeiten können.
Eine Connect-Anfrage über HTTP
Das macht Connect zugänglich. Ein unärer Connect-Aufruf ist ein gewöhnlicher HTTP-POST. Der URL-Pfad stammt direkt aus Ihrem Protobuf-Schema, und der Body ist JSON oder binäres Protobuf ohne zusätzliche Rahmung.
Das Pfadformat ist /<package>.<Service>/<Method>. Eine Greet-Methode für einen GreetService im Paket greet.v1 befindet sich also unter /greet.v1.GreetService/Greet.
Sie können es mit curl aufrufen:
curl \
--header "Content-Type: application/json" \
--data '{"name": "Jane"}' \
http://localhost:8080/greet.v1.GreetService/Greet
Die Antwort ist reines JSON:
{"greeting": "Hello, Jane!"}
Kein benutzerdefinierter Client, kein Proxy, keine Binärdekodierung. Das ist die gesamte Anfrage. Da der Body echtes JSON ist und der Status ein echter HTTP-Statuscode ist, kann jedes HTTP sprechende Tool den Aufruf inspizieren. Dies ist die Eigenschaft, die das Connect-Protokoll von rohem gRPC trennt, wo dieselbe Anfrage in binärer Rahmung verpackt wäre und ihren Status in einem Trailer übertragen würde.
Connect unterstützt zwei Inhaltstypen für unäre Anfragen:
application/jsonfür menschenlesbare JSON-Payloads.application/protofür kompaktes binäres Protobuf.
Sie senden binäres Protobuf, wenn Sie eine kleinere Übertragungsgröße wünschen, und JSON, wenn Sie während der Entwicklung Lesbarkeit wünschen. Um Binärdaten zu senden, ändern Sie den Header und übergeben Sie einen kodierten Body:
curl \
--header "Content-Type: application/proto" \
--data-binary @request.bin \
http://localhost:8080/greet.v1.GreetService/Greet
Streaming-Aufrufe verwenden einen anderen Inhaltstyp (application/connect+proto oder application/connect+json) und verpacken jede Nachricht in einen Umschlag: ein Flags-Byte, eine vier Byte lange Big-Endian-Länge, dann die Nachricht. Unäre Aufrufe überspringen diesen Umschlag vollständig, weshalb sie so sauber auf eine normale HTTP-Anfrage abgebildet werden. Wenn Sie zwischen Drahtformaten für Ihre Payloads wählen, behandelt Protobuf vs. JSON die Kompromisse bei Größe und Lesbarkeit.
Sprachunterstützung und buf-Tooling
ConnectRPC liefert Implementierungen in mehreren Sprachen aus. Go und TypeScript (sowohl für den Browser als auch für Node.js) sind stabil und produktionsreif. Swift ist für Apple-Plattformen verfügbar, mit Kotlin für JVM und Android, und Python befindet sich in der Beta-Phase. Diese Verbreitung ermöglicht es Ihnen, einen Protobuf-Vertrag über ein Go-Backend und ein TypeScript-Frontend hinweg zu teilen, ohne Clients manuell schreiben zu müssen.
Die Codegenerierung erfolgt über die buf-Toolchain. Sie beschreiben Ihren Dienst in einer .proto-Datei und verwenden dann buf-Plugins, um Nachrichten und Connect-Handler zu generieren. Ein Go-Projekt verwendet zwei Plugins: protoc-gen-go für die Protobuf-Nachrichten und protoc-gen-connect-go für die Connect-Handler und Clients.
Die Plugins sind in einer buf.gen.yaml-Datei aufgeführt, und Sie führen die Generierung mit einem Befehl aus:
buf generate
Das erzeugt typisierte Nachrichtenstrukturen sowie den Server- und Client-Code für Ihren Dienst. Von dort aus implementieren Sie die Handler-Methoden und registrieren sie auf einem HTTP-Server. Da der generierte Code auf die net/http-Standardbibliothek in Go abzielt, ziehen Sie keine separate Server-Laufzeitumgebung ein; ein Connect-Handler ist ein normaler HTTP-Handler, den Sie neben Ihren bestehenden Routen einbinden können.
Testen und Debuggen von Connect- und gRPC-Endpunkten
Da unäre Connect-Aufrufe reines HTTP mit einem JSON-Body sind, können Sie sie auf die gleiche Weise testen wie jeden REST-Endpunkt. Das ist ein praktischer Vorteil: Es ist kein spezieller Client erforderlich, um Ihren Dienst während der Entwicklung zu testen.
In Apidog senden Sie eine unäre Connect-Anfrage als HTTP-Anfrage. Stellen Sie die Methode auf POST ein, verwenden Sie die schema-abgeleitete URL wie http://localhost:8080/greet.v1.GreetService/Greet, fügen Sie den Header Content-Type: application/json hinzu und platzieren Sie Ihre Nachricht im JSON-Body:
{"name": "Jane"}
Sie erhalten die JSON-Antwort und einen echten HTTP-Statuscode zurück, den Sie direkt überprüfen können. Apidog ist kein dedizierter Connect-Client, muss es aber auch nicht sein; Sie nutzen die HTTP-Oberfläche, die das Connect-Protokoll bereitstellt, genau wie curl, mit einer Benutzeroberfläche, gespeicherten Anfragen und Historie obendrein. Für eine kurze Einführung in die beteiligten Verben siehe was HTTP-Methoden sind.
Da ein Connect-Server auch gRPC spricht, ist die gRPC-Seite Ihres Dienstes ebenfalls testbar. Apidog unterstützt gRPC-Endpunkte, sodass Sie dieselbe .proto-Datei importieren, die Dienstmethoden durchsuchen und sie mit einer typisierten Anfrage aufrufen können. Das bedeutet, dass ein Tool beide Seiten des Servers abdeckt: das HTTP-freundliche Connect-Protokoll und das native gRPC-Protokoll. Wenn gRPC Ihr Hauptanliegen ist, führt wie man gRPC-APIs effizient testet den Workflow durch.
Sobald Ihre Anfragen sich wie erwartet verhalten, können Sie sie in automatisierte Checks überführen. Speichern Sie Ihre Connect- und gRPC-Aufrufe als Testszenarien und führen Sie sie dann in CI mit dem Apidog CLI aus. Installieren Sie es mit Node:
npm install -g apidog-cli
Führen Sie dann ein gespeichertes Szenario oder eine Suite aus, wobei Sie auf eine Umgebung zeigen und Berichtsformate auswählen:
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t <scenarioOrSuiteId> \
-e <environmentId> \
-r cli,html,junit
Das CLI ist headless, sodass es in jeden CI-Schritt passt, der Node ausführen kann. Es führt gespeicherte Testszenarien und Suiten aus, anstatt Ad-hoc-Anfragen zu senden, was es für Regressionsprüfungen Ihrer Connect- und gRPC-Endpunkte geeignet macht. Eine vollständige Anleitung finden Sie im Apidog CLI-Tutorial zum Testen einer API über die Befehlszeile.
Häufig gestellte Fragen
Ist ConnectRPC dasselbe wie gRPC? Nein. ConnectRPC ist ein Framework, das drei Protokolle implementiert: gRPC, gRPC-Web und sein eigenes Connect-Protokoll. Ein Connect-Server arbeitet mit gRPC-Clients und -Servern zusammen, passt also in das gRPC-Ökosystem, aber das Connect-Protokoll selbst ist ein separates HTTP-basiertes Design, das Browser und Shells direkt aufrufen können.
Brauche ich immer noch einen Proxy wie Envoy, um einen Browser zu erreichen? Nicht für das Connect-Protokoll. Connect läuft über Standard-HTTP, sodass ein Browser einen Connect-Server ohne übersetzenden Proxy aufrufen kann. Sie würden einen Proxy wie Envoy nur dann verwenden, wenn Sie Browser-Traffic zu einem Backend leiten müssen, das natives gRPC und nichts anderes spricht.
Welche Sprachen unterstützt ConnectRPC? Go und TypeScript (Browser und Node.js) sind die stabilen, produktionsreifen Implementierungen. Swift, Kotlin und Python sind ebenfalls verfügbar, wobei Python sich in der Beta-Phase befindet. Alle generieren aus demselben Protobuf-Schema.
Welche Beziehung besteht zwischen Connect und buf? ConnectRPC wurde von Buf entwickelt und verwendet die buf-Toolchain für die Codegenerierung. Sie führen buf generate mit Plugins wie protoc-gen-connect-go aus, um Handler und Clients aus Ihren .proto-Dateien zu erzeugen.
Kann ich einen Connect-Endpunkt mit einem normalen API-Client testen? Ja. Unäre Connect-Aufrufe sind HTTP-POST-Anfragen mit einem JSON- oder Protobuf-Body und einem echten HTTP-Statuscode. Jeder HTTP-Client, einschließlich curl und Apidog, kann eine solche senden. Apidog kann auch die gRPC-Seite desselben Servers aufrufen, indem es die .proto-Datei importiert.