Protobuf et définitions de services
Décrivez votre API en proto.
Protobuf et définitions de services est une leçon Learn Rust Coding gratuite sur CoddyKit. Ceci est la leçon 1 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.
Pourquoi gRPC et Protobuf
gRPC est un cadre RPC haute performance fondé sur HTTP/2 et Protocol Buffers. En Rust, la caisse tonic implémente gRPC de bout en bout.
Protobuf est le langage de définition d’interface (IDL). Vous décrivez une seule fois les messages et les services dans un fichier .proto, puis des générateurs de code produisent des squelettes fortement typés pour le client et le serveur.
Anatomie d’un fichier .proto
Chaque fichier proto déclare une version de syntaxe et un paquet. Le paquet espace les types générés et évite les collisions.
Utilisez proto3 avec tonic. Le nom du paquet correspond au chemin d’un module Rust après la génération.
syntax = "proto3";
package greeter.v1;Définir des messages
Un message est un enregistrement typé. Chaque champ possède un type, un nom et un numéro de champ unique utilisé pour l’encodage sur le réseau.
Les numéros de champ doivent rester stables : ne réutilisez ni ne renumérotez jamais un champ une fois que des données existent, sinon vous rompez la compatibilité.
message HelloRequest {
string name = 1;
int32 age = 2;
}Types scalaires et correspondance avec Rust
Les types scalaires de Protobuf correspondent à des types Rust par l’intermédiaire de prost. string devient String, int32 devient i32, bool devient bool et bytes devient Vec<u8>.
Dans proto3, chaque scalaire possède une valeur par défaut (chaîne vide, 0, faux) ; ils ne sont pas facultatifs sauf indication contraire.
message Metric {
string label = 1;
double value = 2;
bool active = 3;
}Définir un service
Un service regroupe des méthodes RPC. Chaque rpc déclare un nom de méthode, un message de requête et un message de réponse.
tonic génère un trait de serveur et une structure cliente à partir de ce bloc. Implémenter le trait est la manière de fournir le comportement.
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloReply {
string message = 1;
}Les quatre catégories de méthodes RPC
gRPC prend en charge quatre formes de flux : unaire, flux serveur, flux client et flux bidirectionnel.
Vous indiquez un flux avec le mot-clé stream du côté de la requête, de la réponse ou des deux.
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);
}Énumérations dans Protobuf
Les énumérations sont représentées par des entiers. Dans proto3, la première valeur doit porter le numéro 0 et sert de valeur par défaut.
prost génère une énumération Rust ainsi que des fonctions auxiliaires pour convertir depuis le i32 sous-jacent, car des valeurs inconnues peuvent arriver sur le réseau.
enum Status {
STATUS_UNKNOWN = 0;
STATUS_ACTIVE = 1;
STATUS_BANNED = 2;
}Champs imbriqués et répétés
Un champ repeated est une liste et correspond à Vec<T> en Rust. Les messages peuvent être imbriqués ou référencés par leur nom.
Vous pouvez ainsi modéliser des collections et des données composites sans formalités supplémentaires.
message Order {
string id = 1;
repeated Item items = 2;
}
message Item {
string sku = 1;
int32 qty = 2;
}Le type vide et les types bien connus
Pour les méthodes qui ne prennent ni ne renvoient rien, importez google/protobuf/empty.proto et utilisez Empty.
Les autres types bien connus comprennent Timestamp et Duration. tonic fournit ces définitions afin que vous puissiez les importer dans votre compilation.
import "google/protobuf/empty.proto";
service Health {
rpc Ping (google.protobuf.Empty) returns (google.protobuf.Empty);
}Gérer les versions avec les paquets
Inclure une version dans le paquet, comme greeter.v1, permet de faire évoluer une API en toute sécurité. Une modification incompatible est placée dans greeter.v2, tandis que v1 continue de fonctionner.
Cette convention conserve des modules Rust générés propres : greeter::v1 et greeter::v2 coexistent.
package greeter.v1;
// later, a parallel file:
// package greeter.v2;Règles de compatibilité des champs
Ajouter un nouveau champ avec un numéro inédit est rétrocompatible ; les anciens clients l’ignorent. Supprimer un champ est risqué, sauf si vous reserve son numéro et son nom.
La réservation empêche quiconque de réutiliser un numéro de champ retiré et de corrompre le décodage.
message User {
reserved 3, 5;
reserved "legacy_token";
string id = 1;
string email = 2;
}Vérification rapide
Testez votre compréhension des définitions de services proto3.
Récapitulatif
Vous avez défini des services et des messages en proto3 : numéros de champ stables, correspondances des scalaires avec Rust, énumérations, champs répétés et imbriqués, quatre formes de RPC, types bien connus et gestion des versions par les paquets.
Ensuite, vous transformerez ces définitions en code Rust avec tonic-build.
Questions Fréquemment Posées
La leçon « Protobuf et définitions de services » est-elle gratuite ?
Oui — le texte complet de « Protobuf et définitions de services » 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 « Protobuf et définitions de services » ?
Décrivez votre API en proto. 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 1 sur 4.
Combien de temps prend la leçon « Protobuf et définitions de services » ?
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
- Protobuf et définitions de services
- Générer du code avec tonic-build
- Implémenter un serveur gRPC
- Appeler depuis un client gRPC