Generare codice con tonic-build

tonic-build viene eseguito in fase di compilazione e trasforma i file .proto in codice sorgente Rust. Incapsula prost-build per i messaggi e aggiunge i trait dei servizi gRPC e i client.

Viene eseguito da uno script di build di Cargo (build.rs), quindi la generazione avviene automaticamente prima della compilazione del crate.

Sono necessari crate runtime e un crate per la fase di build. tonic e prost sono dipendenze normali; tonic-build va inserito in [build-dependencies].

tonic usa tokio come runtime asincrono, quindi lo includa a sua volta.

Crei build.rs nella radice del crate. Chiami tonic_build::compile_protos indicando il percorso del file proto.

Per impostazione predefinita, questo compila sia il codice client sia quello server e lo scrive nella OUT_DIR di Cargo.

Per un controllo maggiore, usi tonic_build::configure(). È possibile disabilitare la generazione del client o del server, impostare i percorsi di output oppure aggiungere attributi ai tipi.

Qui generiamo il server ma ignoriamo il client, una scelta utile per un crate esclusivamente backend.

Il secondo argomento di compile_protos è l'elenco delle directory di inclusione. Gli import all'interno del proto, come google/protobuf/empty.proto, vengono risolti rispetto a queste radici.

Includa sempre la directory che contiene i file proto, così gli import tra file possono essere risolti.

I file generati vengono scritti nella directory indicata dalla variabile d'ambiente OUT_DIR, con un nome basato sul package proto, ad esempio greeter.v1.rs.

Li si include nel crate con la macro include_proto! all'interno di un modulo.

Per ogni servizio tonic produce un modulo server con un trait (ad esempio greeter_server::Greeter) e un wrapper GreeterServer, oltre a una struct client GreeterClient.

Ogni messaggio diventa una struct Rust che deriva Clone, PartialEq e Message di prost.

Spesso si desiderano derive aggiuntivi sulle struct generate, come serde::Serialize. Usi type_attribute per inserire attributi su tipi specifici o su tutti i tipi con ..

In questo modo i messaggi generati possono essere usati nelle API JSON o nei fixture dei test.

Cargo esegue nuovamente build.rs solo quando ritiene che gli input siano cambiati. Emetta righe cargo:rerun-if-changed affinché le modifiche ai file proto forzino la rigenerazione.

Senza questa configurazione, un proto modificato potrebbe non essere rigenerato finché non viene modificato un file Rust.

Storicamente, tonic-build eseguiva il compilatore protoc, che doveva essere installato. Le versioni moderne possono usare il parser protox interamente scritto in Rust per evitare questa dipendenza.

Se compare un errore relativo a protoc mancante, installi protoc oppure abiliti una funzionalità per un compilatore incluso nel progetto.

Per la reflection o per strumenti avanzati, chieda a tonic-build di generare un insieme di descrittori dei file con file_descriptor_set_path.

I byte risultanti possono essere forniti a tonic-reflection, consentendo a strumenti come grpcurl di individuare i servizi durante l'esecuzione.

Dove viene inserito il codice tonic generato e come viene caricato?

Ha configurato le dipendenze, scritto un build.rs, configurato la generazione di client e server e i percorsi di inclusione, caricato il codice tramite include_proto!, aggiunto i derive, gestito i trigger di ricompilazione e appreso informazioni su protoc e sugli insiemi di descrittori.

Ora implementerà il trait del server generato da tonic.