Protobuf i definicje usług
Opisze Pan/Pani API w proto.
Protobuf i definicje usług to bezpłatna lekcja Learn Rust Coding na CoddyKit. To lekcja 1 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.
Dlaczego gRPC i Protobuf
gRPC to wysokowydajny framework RPC oparty na HTTP/2 i Protocol Buffers. W Rust crate tonic implementuje gRPC od początku do końca.
Protobuf to język definicji interfejsu (IDL). Opisują Państwo komunikaty i usługi jednokrotnie w pliku .proto, a generatory kodu tworzą silnie typowane szkielety klienta i serwera.
Budowa pliku .proto
Każdy plik proto deklaruje wersję składni i pakiet. Pakiet tworzy przestrzeń nazw dla generowanych typów i zapobiega kolizjom.
W przypadku tonic należy używać proto3. Nazwa pakietu po wygenerowaniu mapuje się na ścieżkę modułu Rust.
syntax = "proto3";
package greeter.v1;Definiowanie komunikatów
Komunikat to rekord z określonymi typami. Każde pole ma typ, nazwę i unikatowy numer używany do kodowania przewodowego.
Numery pól muszą pozostać stabilne: po pojawieniu się danych nie wolno ponownie używać numeru pola ani zmieniać jego numeracji, ponieważ powoduje to utratę zgodności.
message HelloRequest {
string name = 1;
int32 age = 2;
}Typy skalarne i mapowanie na Rust
Typy skalarne Protobuf są mapowane na typy Rust za pośrednictwem prost. string staje się typem String, int32 typem i32, bool typem bool, a bytes typem Vec<u8>.
W proto3 każdy skalar ma wartość domyślną (pusty string, 0, false); pola skalarne nie są opcjonalne, chyba że zostaną tak oznaczone.
message Metric {
string label = 1;
double value = 2;
bool active = 3;
}Definiowanie usługi
Element service grupuje metody RPC. Każdy element rpc deklaruje nazwę metody, komunikat żądania i komunikat odpowiedzi.
tonic generuje na podstawie tego bloku trait serwera i strukturę klienta. Zaimplementowanie traitu jest sposobem dostarczenia zachowania.
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloReply {
string message = 1;
}Cztery rodzaje metod RPC
gRPC obsługuje cztery rodzaje przesyłania strumieniowego: unary, strumieniowanie z serwera, strumieniowanie od klienta oraz strumieniowanie dwukierunkowe.
Strumień sygnalizuje się słowem kluczowym stream po stronie żądania, odpowiedzi albo po obu stronach.
service Chat {
rpc Unary (Msg) returns (Msg);
rpc ServerStream (Msg) returns (stream Msg);
rpc ClientStream (stream Msg) returns (Msg);
rpc BiDi (stream Msg) returns (stream Msg);
}Wyliczenia w Protobuf
Wyliczenia są oparte na liczbach całkowitych. W proto3 pierwsza wartość musi mieć numer 0 i pełni funkcję wartości domyślnej.
prost generuje wyliczenie Rust oraz funkcje pomocnicze do konwersji z bazowego typu i32, ponieważ przez przewód mogą nadejść nieznane wartości.
enum Status {
STATUS_UNKNOWN = 0;
STATUS_ACTIVE = 1;
STATUS_BANNED = 2;
}Pola zagnieżdżone i powtarzalne
Pole repeated jest listą i mapuje się w Rust na Vec<T>. Komunikaty mogą być zagnieżdżone albo wskazywane po nazwie.
Pozwala to modelować kolekcje i złożone dane bez dodatkowych formalności.
message Order {
string id = 1;
repeated Item items = 2;
}
message Item {
string sku = 1;
int32 qty = 2;
}Typ Empty i typy dobrze znane
W przypadku metod, które nie przyjmują ani nie zwracają żadnych danych, należy zaimportować google/protobuf/empty.proto i użyć Empty.
Inne typy dobrze znane to między innymi Timestamp i Duration. tonic dostarcza ich definicje, więc można je importować podczas budowania.
import "google/protobuf/empty.proto";
service Health {
rpc Ping (google.protobuf.Empty) returns (google.protobuf.Empty);
}Wersjonowanie za pomocą pakietów
Umieszczenie wersji w pakiecie, na przykład greeter.v1, pozwala bezpiecznie rozwijać API. Zmiana niezgodna wstecz trafia do greeter.v2, podczas gdy v1 nadal obsługuje żądania.
Ta konwencja utrzymuje porządek w wygenerowanych modułach Rust: greeter::v1 i greeter::v2 mogą współistnieć.
package greeter.v1;
// later, a parallel file:
// package greeter.v2;Zasady zgodności pól
Dodanie nowego pola z nowym numerem jest zgodne wstecz; starsi klienci je ignorują. Usunięcie pola jest ryzykowne, chyba że jego numer i nazwa zostaną oznaczone jako reserve.
Rezerwacja uniemożliwia ponowne użycie wycofanego numeru pola i uszkodzenie dekodowania.
message User {
reserved 3, 5;
reserved "legacy_token";
string id = 1;
string email = 2;
}Szybkie sprawdzenie
Proszę sprawdzić swoje rozumienie definicji usług proto3.
Podsumowanie
Zdefiniowali Państwo usługi i komunikaty w proto3: stabilne numery pól, mapowania typów skalarnych na Rust, wyliczenia, pola powtarzalne i zagnieżdżone, cztery rodzaje RPC, typy dobrze znane oraz wersjonowanie za pomocą pakietów.
W następnym kroku przekształcą Państwo te definicje w kod Rust za pomocą tonic-build.
Ucz się Rust dzięki korepetycjom AI — za darmo
Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.
- Kursy
- 39
- Lekcje
- 144
Często zadawane pytania
Czy lekcja „Protobuf i definicje usług” jest bezpłatna?
Tak — pełny tekst „Protobuf i definicje usług” 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 „Protobuf i definicje usług”?
Opisze Pan/Pani API w proto. Ć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 1 z 4.
Ile czasu zajmuje lekcja „Protobuf i definicje usług”?
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
- Protobuf i definicje usług
- Generowanie kodu za pomocą tonic-build
- Implementowanie serwera gRPC
- Wywoływanie z klienta gRPC