Learn Rust Coding · Lektion

Protobuf- und Servicedefinitionen

Beschreiben Sie Ihre API in proto.

Protobuf- und Servicedefinitionen ist eine kostenlose Learn Rust Coding-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des Learn Rust Coding-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der Learn Rust Coding-Kurs umfasst insgesamt 4 Lektionen.

Warum gRPC und Protobuf

gRPC ist ein leistungsstarkes RPC-Framework auf Grundlage von HTTP/2 und Protocol Buffers. In Rust implementiert die Crate tonic gRPC vollständig.

Protobuf ist die Sprache zur Schnittstellendefinition (IDL). Sie beschreiben Nachrichten und Dienste einmal in einer .proto-Datei, und Codegeneratoren erzeugen stark typisierte Client- und Server-Stubs.

Aufbau einer .proto-Datei

Jede Proto-Datei deklariert eine Syntaxversion und ein Package. Das Package dient als Namespace für generierte Typen und verhindert Namenskonflikte.

Verwenden Sie für tonic proto3. Der Package-Name wird nach der Generierung einem Rust-Modulpfad zugeordnet.

syntax = "proto3";

package greeter.v1;

Nachrichten definieren

Eine Nachricht ist ein typisierter Datensatz. Jedes Feld besitzt einen Typ, einen Namen und eine eindeutige Feldnummer, die für die Wire-Kodierung verwendet wird.

Feldnummern müssen stabil bleiben: Verwenden Sie eine Feldnummer niemals erneut und ändern Sie sie nicht, sobald Daten existieren, sonst brechen Sie die Kompatibilität.

message HelloRequest {
  string name = 1;
  int32 age = 2;
}

Skalare Typen und ihre Rust-Zuordnung

Protobuf-Skalare werden über prost Rust-Typen zugeordnet. string wird zu String, int32 zu i32, bool zu bool und bytes zu Vec<u8>.

In proto3 besitzt jeder skalare Wert einen Standardwert (leere Zeichenkette, 0, false); optional sind sie nur, wenn sie entsprechend markiert wurden.

message Metric {
  string label = 1;
  double value = 2;
  bool active = 3;
}

Einen Dienst definieren

Ein service gruppiert RPC-Methoden. Jedes rpc deklariert einen Methodennamen, eine Request-Nachricht und eine Response-Nachricht.

tonic generiert aus diesem Block ein Server-Trait und eine Client-Struktur. Durch die Implementierung des Traits stellen Sie das Verhalten bereit.

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloReply {
  string message = 1;
}

Vier Arten von RPC-Methoden

gRPC unterstützt vier Streaming-Formen: unär, Server-Streaming, Client-Streaming und bidirektionales Streaming.

Sie kennzeichnen einen Stream mit dem Schlüsselwort stream auf der Request- oder Response-Seite oder auf beiden.

service Chat {
  rpc Unary (Msg) returns (Msg);
  rpc ServerStream (Msg) returns (stream Msg);
  rpc ClientStream (stream Msg) returns (Msg);
  rpc BiDi (stream Msg) returns (stream Msg);
}

Enums in Protobuf

Enums werden durch Ganzzahlen repräsentiert. In proto3 muss der erste Wert die Nummer 0 besitzen und dient als Standardwert.

prost generiert ein Rust-Enum sowie Hilfsfunktionen zur Konvertierung aus dem zugrunde liegenden i32, da unbekannte Werte über die Leitung eintreffen können.

enum Status {
  STATUS_UNKNOWN = 0;
  STATUS_ACTIVE = 1;
  STATUS_BANNED = 2;
}

Verschachtelte und wiederholte Felder

Ein Feld mit repeated ist eine Liste und wird in Rust Vec<T> zugeordnet. Nachrichten können verschachtelt oder über ihren Namen referenziert werden.

So können Sie Sammlungen und zusammengesetzte Nutzdaten ohne zusätzlichen Aufwand modellieren.

message Order {
  string id = 1;
  repeated Item items = 2;
}

message Item {
  string sku = 1;
  int32 qty = 2;
}

Empty und bekannte Typen

Für Methoden, die nichts entgegennehmen oder zurückgeben, importieren Sie google/protobuf/empty.proto und verwenden Empty.

Weitere bekannte Typen sind Timestamp und Duration. tonic liefert diese Definitionen mit, sodass Sie sie in Ihrem Build importieren können.

import "google/protobuf/empty.proto";

service Health {
  rpc Ping (google.protobuf.Empty) returns (google.protobuf.Empty);
}

Versionierung mit Packages

Wenn Sie eine Version in das Package aufnehmen, etwa greeter.v1, können Sie eine API sicher weiterentwickeln. Eine inkompatible Änderung kommt in greeter.v2, während v1 weiterhin bedient wird.

Diese Konvention hält die generierten Rust-Module übersichtlich: greeter::v1 und greeter::v2 können nebeneinander bestehen.

package greeter.v1;
// later, a parallel file:
// package greeter.v2;

Regeln für die Feldkompatibilität

Das Hinzufügen eines neuen Feldes mit einer bisher nicht verwendeten Nummer ist abwärtskompatibel; alte Clients ignorieren es. Das Entfernen eines Feldes ist riskant, sofern Sie nicht seine Nummer und seinen Namen mit reserve reservieren.

Die Reservierung verhindert, dass jemand eine ausgemusterte Feldnummer erneut verwendet und dadurch die Dekodierung beschädigt.

message User {
  reserved 3, 5;
  reserved "legacy_token";
  string id = 1;
  string email = 2;
}

Kurze Überprüfung

Testen Sie Ihr Verständnis von proto3-Dienstdefinitionen.

Zusammenfassung

Sie haben Dienste und Nachrichten in proto3 definiert: stabile Feldnummern, Zuordnungen von Skalaren zu Rust-Typen, Enums, wiederholte und verschachtelte Felder, die vier RPC-Formen, bekannte Typen und Versionierung über Packages.

Als Nächstes wandeln Sie diese Definitionen mit tonic-build in Rust-Code um.

Häufig gestellte Fragen

Ist die Lektion „Protobuf- und Servicedefinitionen“ kostenlos?

Ja — der vollständige Text von „Protobuf- und Servicedefinitionen“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des Learn Rust Coding-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der Learn Rust Coding-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Protobuf- und Servicedefinitionen“?

Beschreiben Sie Ihre API in proto. Du übst Learn Rust Coding mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um Learn Rust Coding zu starten?

Keine Vorkenntnisse erforderlich. Learn Rust Coding auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.

Wie lange dauert die Lektion „Protobuf- und Servicedefinitionen“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser Learn Rust Coding-Lektion Code schreiben und ausführen?

Ja. Jede Learn Rust Coding-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

← Zurück zu Learn Rust Coding