Lär dig programmera i Rust · Lektion

Generera kod med tonic-build

Kompilera proto till Rust.

Lektion 2 av 413 steg

Generera kod med tonic-build är en gratis lektion i Lär dig programmera i Rust på CoddyKit. Detta är lektion 2 av 4. Du kan läsa vilka 3 lektioner som helst i den här lärvägen kostnadsfritt i sin helhet – därefter låser CoddyKit PRO upp alla lektioner, plus praktisk övning med en inbyggd kodredigerare och en AI-lärare dygnet runt. Den ingår i lärvägen för Lär dig programmera i Rust, och Era framsteg synkroniseras mellan webben och CoddyKit-appen. Kursen i Lär dig programmera i Rust innehåller totalt 4 lektioner.

Vad tonic-build gör

tonic-build körs vid kompilering och omvandlar dina .proto-filer till Rust-källkod. Det kapslar in prost-build för meddelanden och lägger till gRPC-tjänsternas traits och klienter ovanpå.

Det körs från ett Cargo-byggskript (build.rs), så genereringen sker automatiskt innan ditt crate kompileras.

Cargo-beroenden

Du behöver runtime-crates och ett crate för byggtiden. tonic och prost är vanliga beroenden; tonic-build placeras under [build-dependencies].

tonic använder tokio som async-runtime, så ta med det också.

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

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

Ett minimalt build.rs

Skapa build.rs i cratets rotkatalog. Anropa tonic_build::compile_protos med sökvägen till din proto-fil.

Detta kompilerar både klient- och serverkod som standard och skriver den till Cargos OUT_DIR.

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

Konfigurera buildern

Använd tonic_build::configure() om du vill ha mer kontroll. Du kan inaktivera generering av klient eller server, ange utdatasökvägar eller lägga till typattribut.

Här genererar vi servern men hoppar över klienten, vilket är användbart för ett renodlat backend-crate.

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

Inkluderingssökvägar

Det andra argumentet till compile_protos är listan över inkluderingskataloger. Importer i din proto-fil, till exempel google/protobuf/empty.proto, löses mot dessa rotkataloger.

Inkludera alltid katalogen som innehåller dina proto-filer, så att importer mellan filer kan lösas.

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

Var koden hamnar

Genererade filer skrivs till katalogen i miljövariabeln OUT_DIR och namnges efter proto-paketet, till exempel greeter.v1.rs.

Du tar in dem i ditt crate med makrot include_proto! inuti en modul.

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

Vad som genereras

För varje tjänst producerar tonic en servermodul med ett trait (till exempel greeter_server::Greeter) och en GreeterServer-wrapper, samt en klientstruct GreeterClient.

Varje meddelande blir en Rust-struct som härleder Clone, PartialEq och prosts Message.

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

Lägga till derives med type_attribute

Ofta vill du lägga till extra derives på genererade structar, till exempel serde::Serialize. Använd type_attribute för att injicera attribut på specifika typer eller på alla typer med ..

Det gör att genererade meddelanden kan användas i JSON-API:er eller test-fixtures.

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

Utlösa ombyggnader

Cargo kör bara om build.rs när det bedömer att indata har ändrats. Skriv ut rader med cargo:rerun-if-changed så att ändringar i proto-filer tvingar fram ny generering.

Utan detta kanske en ändrad proto-fil inte genereras om förrän du ändrar en Rust-fil.

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

Krav på protoc

Historiskt startade tonic-build kompilatorn protoc som en extern process, och den behövde vara installerad. Moderna versioner kan använda den Rust-baserade parsern protox för att undvika det beroendet.

Om du ser ett fel om att protoc saknas kan du installera protoc eller aktivera en funktion för en medföljande kompilator.

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

Fildeskriptorsamlingar

För reflection eller avancerade verktyg kan du be tonic-build att skapa en fildeskriptorsamling med file_descriptor_set_path.

De resulterande byten kan matas till tonic-reflection, så att verktyg som grpcurl kan upptäcka dina tjänster under körning.

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

Snabbkontroll

Vart hamnar genererad tonic-kod och hur läses den in?

Besvara frågan i den interaktiva lektionen

Sammanfattning

Du konfigurerade beroenden, skrev ett build.rs, konfigurerade generering av klient och server samt inkluderingssökvägar, läste in kod via include_proto!, lade till derives, hanterade ombyggnadstriggers och lärde dig om protoc och deskriptorsamlingar.

Nu ska du implementera det servertrait som tonic genererade.

Gratis att börja

Lär dig Rust med en AI-lärare – gratis

Skriv och kör riktig kod i webbläsaren, få omedelbar hjälp av en AI-lärare dygnet runt och fortsätt där du slutade – på webben eller i appen.

Kurser: 39
Lektioner: 144

Börja lära dig gratis Visa hela kursen

Vanliga frågor

Är lektionen ”Generera kod med tonic-build” gratis?

Ja – du kan läsa vilka 3 lektioner som helst i lärvägen Lär dig programmera i Rust, inklusive ”Generera kod med tonic-build”, kostnadsfritt i sin helhet här på webben. Därefter låser CoddyKit PRO upp alla lektioner, plus interaktiv övning med en inbyggd kodredigerare och en AI-lärare dygnet runt. Kursen i Lär dig programmera i Rust innehåller totalt 4 lektioner.

Vad lär jag mig i ”Generera kod med tonic-build”?

Kompilera proto till Rust. Ni övar på Lär dig programmera i Rust med praktisk kod som körs direkt i webbläsaren, medan en AI-handledare som är tillgänglig dygnet runt svarar på Era frågor under lektionen.

Behöver jag någon erfarenhet för att börja lära mig Lär dig programmera i Rust?

Du behöver inga förkunskaper. Utbildningen i Lär dig programmera i Rust på CoddyKit är upplagd för allt från nybörjare till avancerade elever, så att du kan börja här eller från början och gå fram i din egen takt. Detta är lektion 2 av 4.

Hur lång tid tar lektionen ”Generera kod med tonic-build”?

De flesta CoddyKit-lektioner tar cirka 5–10 minuter. Varje lektion är kort och interaktiv, så att du gör stadiga framsteg och kan fortsätta precis där du slutade – på webben eller i appen.

Kan jag skriva och köra kod i den här Lär dig programmera i Rust-lektionen?

Ja. Varje Lär dig programmera i Rust-lektion innehåller en inbyggd kodredigerare, så att du kan skriva och köra riktig kod direkt i webbläsaren och få omedelbar AI-feedback – utan lokal installation.

Alla lektioner i den här kursen

← Tillbaka till Lär dig programmera i Rust