Code mit tonic-build generieren

tonic-build wird zur Kompilierzeit ausgeführt und wandelt Ihre .proto-Dateien in Rust-Quellcode um. Es kapselt prost-build für Nachrichten und ergänzt darauf aufbauend die gRPC-Service-Traits und -Clients.

Es wird über ein Cargo-Build-Skript (build.rs) ausgeführt, sodass die Generierung automatisch vor der Kompilierung Ihrer Crate erfolgt.

Sie benötigen Crates zur Laufzeit und eine Crate zur Build-Zeit. tonic und prost sind normale Abhängigkeiten; tonic-build gehört unter [build-dependencies].

tonic verwendet tokio als asynchrone Laufzeitumgebung, daher müssen Sie auch diese einbinden.

Erstellen Sie build.rs im Stammverzeichnis der Crate. Rufen Sie tonic_build::compile_protos mit dem Pfad zu Ihrer Proto-Datei auf.

Standardmäßig werden dabei sowohl Client- als auch Server-Code kompiliert und in das Cargo-OUT_DIR geschrieben.

Für mehr Kontrolle verwenden Sie tonic_build::configure(). Sie können die Generierung des Clients oder Servers deaktivieren, Ausgabepfade festlegen oder Typattribute hinzufügen.

Hier generieren wir den Server, überspringen aber den Client – nützlich für eine reine Backend-Crate.

Das zweite Argument von compile_protos ist die Liste der Include-Verzeichnisse. Imports innerhalb Ihrer Proto-Datei, etwa google/protobuf/empty.proto, werden anhand dieser Stammverzeichnisse aufgelöst.

Binden Sie immer das Verzeichnis ein, das Ihre Proto-Dateien enthält, damit dateiübergreifende Imports aufgelöst werden können.

Generierte Dateien werden in das Verzeichnis geschrieben, das in der Umgebungsvariable OUT_DIR angegeben ist. Ihr Name basiert auf dem Proto-Paket, zum Beispiel greeter.v1.rs.

Sie binden sie mit dem Makro include_proto! innerhalb eines Moduls in Ihre Crate ein.

Für jeden Service erzeugt tonic ein Servermodul mit einem Trait (zum Beispiel greeter_server::Greeter) und einem Wrapper GreeterServer sowie eine Client-Struktur GreeterClient.

Jede Nachricht wird zu einer Rust-Struktur, die Clone, PartialEq und prosts Message ableitet.

Oft benötigen Sie zusätzliche Derives für generierte Strukturen, etwa serde::Serialize. Verwenden Sie type_attribute, um Attribute auf bestimmte Typen oder mit . auf alle Typen anzuwenden.

So können generierte Nachrichten in JSON-APIs oder Test-Fixtures verwendet werden.

Cargo führt build.rs nur dann erneut aus, wenn es annimmt, dass sich Eingaben geändert haben. Geben Sie Zeilen mit cargo:rerun-if-changed aus, damit Änderungen an Proto-Dateien eine erneute Generierung erzwingen.

Andernfalls wird eine geänderte Proto-Datei möglicherweise erst dann neu generiert, wenn Sie eine Rust-Datei ändern.

Historisch hat tonic-build den Compiler protoc als externen Prozess aufgerufen, der installiert sein musste. Moderne Versionen können den in reinem Rust geschriebenen Parser protox verwenden und diese Abhängigkeit dadurch vermeiden.

Wenn Sie einen Fehler wegen eines fehlenden protoc sehen, installieren Sie protoc oder aktivieren Sie ein Feature für einen mitgelieferten Compiler.

Für Reflection oder fortgeschrittene Werkzeuge können Sie tonic-build anweisen, mit file_descriptor_set_path eine Dateideskriptorsammlung auszugeben.

Die resultierenden Bytes können an tonic-reflection übergeben werden, sodass Werkzeuge wie grpcurl Ihre Services zur Laufzeit erkennen können.

Wohin gelangt der generierte tonic-Code, und wie wird er geladen?

Sie haben Abhängigkeiten eingerichtet, ein build.rs geschrieben, die Generierung von Client und Server sowie Include-Pfade konfiguriert, Code über include_proto! geladen, Derives hinzugefügt, Auslöser für Neubuilds behandelt und protoc sowie Deskriptorsammlungen kennengelernt.

Als Nächstes implementieren Sie den von tonic generierten Server-Trait.