Learn Rust Coding · Lekcja

Generowanie kodu za pomocą tonic-build

Skompiluje Pan/Pani proto do Rusta.

Generowanie kodu za pomocą tonic-build to bezpłatna lekcja Learn Rust Coding na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Learn Rust Coding, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Learn Rust Coding zawiera 4 lekcji w sumie.

Działanie tonic-build

tonic-build działa w czasie kompilacji i przekształca pliki .proto w kod źródłowy Rust. Opakowuje prost-build dla komunikatów, a dodatkowo generuje cechy usług gRPC i klientów.

Jest uruchamiany ze skryptu kompilacji Cargo (build.rs), więc generowanie odbywa się automatycznie przed skompilowaniem skrzynki.

Zależności Cargo

Potrzebne są skrzynki używane w czasie działania oraz skrzynka używana podczas kompilacji. tonic i prost to zwykłe zależności, natomiast tonic-build należy umieścić w sekcji [build-dependencies].

tonic korzysta z tokio jako asynchronicznego środowiska wykonawczego, więc należy również je dołączyć.

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

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

Minimalny build.rs

Utwórz plik build.rs w katalogu głównym skrzynki. Wywołaj tonic_build::compile_protos, przekazując ścieżkę do pliku proto.

Domyślnie kompiluje to zarówno kod klienta, jak i serwera, a następnie zapisuje go w katalogu Cargo OUT_DIR.

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

Konfigurowanie generatora

Aby uzyskać większą kontrolę, użyj tonic_build::configure(). Można wyłączyć generowanie klienta lub serwera, ustawić ścieżki wyjściowe albo dodać atrybuty typów.

W tym przypadku generujemy serwer, ale pomijamy klienta, co jest przydatne w skrzynce przeznaczonej wyłącznie dla backendu.

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

Ścieżki dołączania

Drugim argumentem funkcji compile_protos jest lista katalogów dołączania. Importy w pliku proto, takie jak google/protobuf/empty.proto, są wyszukiwane względem tych katalogów głównych.

Zawsze należy dołączyć katalog zawierający pliki proto, aby importy między plikami były poprawnie rozwiązywane.

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

Gdzie trafia kod

Wygenerowane pliki są zapisywane w katalogu wskazanym przez zmienną środowiskową OUT_DIR i otrzymują nazwę na podstawie pakietu proto, na przykład greeter.v1.rs.

Dołączasz je do skrzynki za pomocą makra include_proto! wewnątrz modułu.

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

Co jest generowane

Dla każdej usługi tonic generuje moduł serwera z cechą (na przykład greeter_server::Greeter) oraz opakowaniem GreeterServer, a także strukturę klienta GreeterClient.

Każdy komunikat staje się strukturą Rust implementującą makra pochodne Clone, PartialEq oraz Message biblioteki prost.

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

Dodawanie makr pochodnych za pomocą type_attribute

Do wygenerowanych struktur często potrzebne są dodatkowe makra pochodne, takie jak serde::Serialize. Użyj type_attribute, aby wstrzyknąć atrybuty do określonych typów lub do wszystkich typów za pomocą ..

Dzięki temu wygenerowane komunikaty można wykorzystywać w interfejsach JSON lub danych testowych.

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

Wyzwalanie ponownej kompilacji

Cargo ponownie uruchamia build.rs tylko wtedy, gdy uzna, że dane wejściowe się zmieniły. Wygeneruj wiersze cargo:rerun-if-changed, aby edycja plików proto wymuszała ponowne generowanie.

Bez tego zmieniony plik proto może nie zostać ponownie wygenerowany do momentu zmodyfikowania pliku 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(())
}

Wymaganie protoc

Historycznie tonic-build uruchamiał kompilator protoc jako zewnętrzny proces, więc musiał on być zainstalowany. Współczesne wersje mogą korzystać z napisanego w Rust parsera protox, aby uniknąć tej zależności.

Jeśli pojawi się błąd informujący o braku protoc, zainstaluj protoc albo włącz funkcję kompilatora dołączanego do pakietu.

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

Zestawy deskryptorów plików

Na potrzeby refleksji lub zaawansowanych narzędzi poleć tonic-build wygenerowanie zestawu deskryptorów plików za pomocą file_descriptor_set_path.

Powstałe bajty można przekazać do tonic-reflection, dzięki czemu narzędzia takie jak grpcurl mogą wykrywać usługi w czasie działania.

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

Szybkie sprawdzenie

Dokąd trafia wygenerowany kod tonic i w jaki sposób jest ładowany?

Podsumowanie

Skonfigurowałeś zależności, napisałeś plik build.rs, skonfigurowałeś generowanie klienta i serwera oraz ścieżki dołączania, załadowałeś kod za pomocą include_proto!, dodałeś makra pochodne, obsłużyłeś wyzwalacze ponownej kompilacji oraz poznałeś protoc i zestawy deskryptorów.

Teraz zaimplementujesz cechę serwera wygenerowaną przez tonic.

Często zadawane pytania

Czy lekcja „Generowanie kodu za pomocą tonic-build” jest bezpłatna?

Tak — pełny tekst „Generowanie kodu za pomocą tonic-build” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Learn Rust Coding, przejdź na CoddyKit PRO. Kurs Learn Rust Coding zawiera 4 lekcji w sumie.

Co nauczysz się w „Generowanie kodu za pomocą tonic-build”?

Skompiluje Pan/Pani proto do Rusta. Ćwiczysz Learn Rust Coding z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Learn Rust Coding?

Nie wymagamy żadnego doświadczenia. Learn Rust Coding w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Generowanie kodu za pomocą tonic-build”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Learn Rust Coding?

Tak. Każda lekcja Learn Rust Coding zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do Learn Rust Coding