Learn Rust Coding · Leçon

Générer du code avec tonic-build

Compilez le proto en Rust.

Générer du code avec tonic-build est une leçon Learn Rust Coding gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Learn Rust Coding, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Learn Rust Coding comprend 4 leçons au total.

Rôle de tonic-build

tonic-build s’exécute au moment de la compilation et transforme vos fichiers .proto en code source Rust. Il s’appuie sur prost-build pour les messages et ajoute par-dessus les traits de service et les clients gRPC.

Il est lancé depuis un script de compilation Cargo (build.rs), de sorte que la génération s’effectue automatiquement avant la compilation de votre caisse.

Dépendances Cargo

Vous avez besoin de caisses d’exécution et d’une caisse utilisée lors de la compilation. tonic et prost sont des dépendances normales ; tonic-build va dans [build-dependencies].

tonic utilise tokio comme environnement d’exécution asynchrone ; incluez-le également.

[dependencies]
tonic = "0.12"
prost = "0.13"
tokio = { version = "1", features = ["full"] }

[build-dependencies]
tonic-build = "0.12"

Un build.rs minimal

Créez build.rs à la racine de la caisse. Appelez tonic_build::compile_protos en lui transmettant le chemin vers votre fichier proto.

Par défaut, cela compile le code du client et du serveur et l’écrit dans le OUT_DIR de Cargo.

fn main() -> Result<(), Box<dyn std::error::Error>> {
    tonic_build::compile_protos("proto/greeter.proto")?;
    Ok(())
}

Configurer le générateur

Pour davantage de contrôle, utilisez tonic_build::configure(). Vous pouvez désactiver la génération du client ou du serveur, définir les chemins de sortie ou ajouter des attributs de type.

Ici, nous générons le serveur sans le client, ce qui est utile pour une caisse purement dédiée au serveur.

tonic_build::configure()
    .build_client(false)
    .build_server(true)
    .compile_protos(&["proto/greeter.proto"], &["proto"])?;

Chemins d’inclusion

Le deuxième argument de compile_protos est la liste des répertoires d’inclusion. Les imports présents dans votre proto, comme google/protobuf/empty.proto, sont recherchés dans ces racines.

Incluez toujours le répertoire qui contient vos fichiers proto afin que les imports entre fichiers soient résolus.

tonic_build::configure()
    .compile_protos(
        &["proto/greeter.proto", "proto/health.proto"],
        &["proto"],
    )?;

Emplacement du code

Les fichiers générés sont écrits dans le répertoire indiqué par la variable d’environnement OUT_DIR, avec un nom dérivé du paquet proto, par exemple greeter.v1.rs.

Vous les intégrez à votre caisse avec la macro include_proto! à l’intérieur d’un module.

pub mod greeter {
    pub mod v1 {
        tonic::include_proto!("greeter.v1");
    }
}

Code généré

Pour chaque service, tonic produit un module serveur contenant un trait (par exemple greeter_server::Greeter) et un conteneur GreeterServer, ainsi qu’une structure cliente GreeterClient.

Chaque message devient une structure Rust dérivant Clone, PartialEq et le Message de prost.

// generated (sketch):
// pub mod greeter_server { pub trait Greeter { /* methods */ } }
// pub mod greeter_client { pub struct GreeterClient<T> { /* ... */ } }

Ajouter des dérivations avec type_attribute

Vous souhaitez souvent ajouter des dérivations aux structures générées, comme serde::Serialize. Utilisez type_attribute pour injecter des attributs sur des types précis ou sur tous les types avec ..

Les messages générés peuvent ainsi alimenter des API JSON ou des montages de test.

tonic_build::configure()
    .type_attribute(".", "#[derive(serde::Serialize)]")
    .compile_protos(&["proto/greeter.proto"], &["proto"])?;

Déclencher les recompilations

Cargo ne relance build.rs que lorsqu’il pense que les entrées ont changé. Émettez des lignes cargo:rerun-if-changed afin que les modifications des fichiers proto forcent une nouvelle génération.

Sans cela, un proto modifié peut ne pas être régénéré avant que vous ne touchiez à un fichier Rust.

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("cargo:rerun-if-changed=proto/greeter.proto");
    tonic_build::compile_protos("proto/greeter.proto")?;
    Ok(())
}

Dépendance à protoc

Historiquement, tonic-build lançait le compilateur protoc, qui devait être installé. Les versions modernes peuvent utiliser l’analyseur pur Rust protox pour éviter cette dépendance.

Si une erreur signale l’absence de protoc, installez protoc ou activez une fonctionnalité fournissant un compilateur intégré.

// In CI you may install protoc, e.g.:
// apt-get install -y protobuf-compiler

Ensembles de descripteurs de fichiers

Pour la réflexion ou les outils avancés, demandez à tonic-build d’émettre un ensemble de descripteurs de fichiers avec file_descriptor_set_path.

Les octets ainsi obtenus peuvent alimenter tonic-reflection, permettant à des outils comme grpcurl de découvrir vos services à l’exécution.

tonic_build::configure()
    .file_descriptor_set_path(
        std::env::var("OUT_DIR").unwrap() + "/greeter.bin")
    .compile_protos(&["proto/greeter.proto"], &["proto"])?;

Vérification rapide

Où le code tonic généré est-il placé et comment est-il chargé ?

Récapitulatif

Vous avez configuré les dépendances, écrit un build.rs, configuré la génération du client et du serveur ainsi que les chemins d’inclusion, chargé le code via include_proto!, ajouté des dérivations, géré les déclencheurs de recompilation et découvert protoc ainsi que les ensembles de descripteurs.

Ensuite, vous implémenterez le trait de serveur généré par tonic.

Questions Fréquemment Posées

La leçon « Générer du code avec tonic-build » est-elle gratuite ?

Oui — le texte complet de « Générer du code avec tonic-build » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Learn Rust Coding, passe à CoddyKit PRO. Le cours Learn Rust Coding comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Générer du code avec tonic-build » ?

Compilez le proto en Rust. Tu pratiques Learn Rust Coding avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer Learn Rust Coding ?

Aucune expérience préalable n'est requise. Learn Rust Coding sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.

Combien de temps prend la leçon « Générer du code avec tonic-build » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon Learn Rust Coding ?

Oui. Chaque leçon Learn Rust Coding inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

← Retour à Learn Rust Coding