Definições de Protobuf e serviços
Descreva sua API em proto.
Definições de Protobuf e serviços é uma aula grátis de Learn Rust Coding no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Learn Rust Coding, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Learn Rust Coding inclui 4 aulas no total.
Por que gRPC e Protobuf
gRPC é uma estrutura de RPC de alto desempenho baseada em HTTP/2 e Protocol Buffers. No Rust, o crate tonic implementa gRPC de ponta a ponta.
Protobuf é a linguagem de definição de interface (IDL). Você descreve mensagens e serviços uma vez em um arquivo .proto, e geradores de código produzem implementações de cliente e servidor com tipagem forte.
Anatomia de um Arquivo .proto
Todo arquivo proto declara uma versão de sintaxe e um pacote. O pacote cria um espaço de nomes para os tipos gerados e evita colisões.
Use proto3 com tonic. Depois da geração, o nome do pacote é mapeado para um caminho de módulo do Rust.
syntax = "proto3";
package greeter.v1;Definindo Mensagens
Uma mensagem é um registro tipado. Cada campo tem um tipo, um nome e um número de campo exclusivo usado na codificação para transmissão.
Os números dos campos devem permanecer estáveis: nunca reutilize nem renumere um campo depois que houver dados, ou você quebrará a compatibilidade.
message HelloRequest {
string name = 1;
int32 age = 2;
}Tipos Escalares e o Mapeamento para Rust
Os tipos escalares do Protobuf são mapeados para tipos do Rust por meio de prost. string se torna String, int32 se torna i32, bool se torna bool e bytes se torna Vec<u8>.
No proto3, todo escalar tem um valor padrão (string vazia, 0, falso); eles não são opcionais a menos que isso seja indicado.
message Metric {
string label = 1;
double value = 2;
bool active = 3;
}Definindo um Serviço
Um service agrupa métodos RPC. Cada rpc declara um nome de método, uma mensagem de requisição e uma mensagem de resposta.
tonic gera um traço de servidor e uma estrutura de cliente a partir deste bloco. Implementar o traço é a forma de fornecer o comportamento.
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloReply {
string message = 1;
}Quatro Tipos de Métodos RPC
gRPC oferece quatro formatos de transmissão: unária, transmissão do servidor, transmissão do cliente e transmissão bidirecional.
Você indica uma transmissão com a palavra-chave stream no lado da requisição ou da resposta, ou em ambos.
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);
}Enumerações no Protobuf
As enumerações são baseadas em inteiros. No proto3, o primeiro valor deve ser numerado como 0 e funciona como padrão.
prost gera uma enumeração do Rust e auxiliares para converter a partir do i32 subjacente, pois valores desconhecidos podem chegar pela transmissão.
enum Status {
STATUS_UNKNOWN = 0;
STATUS_ACTIVE = 1;
STATUS_BANNED = 2;
}Campos Aninhados e Repetidos
Um campo repeated é uma lista e é mapeado para Vec<T> no Rust. As mensagens podem ser aninhadas ou referenciadas pelo nome.
Isso permite modelar coleções e cargas compostas sem uma elaboração extra.
message Order {
string id = 1;
repeated Item items = 2;
}
message Item {
string sku = 1;
int32 qty = 2;
}O Tipo Vazio e os Tipos Conhecidos
Para métodos que não recebem nem retornam nada, importe google/protobuf/empty.proto e use Empty.
Outros tipos conhecidos incluem Timestamp e Duration. O tonic fornece essas definições, para que você possa importá-las na compilação.
import "google/protobuf/empty.proto";
service Health {
rpc Ping (google.protobuf.Empty) returns (google.protobuf.Empty);
}Versionamento com Pacotes
Incluir uma versão no pacote, como greeter.v1, permite evoluir uma API com segurança. Uma alteração incompatível vai para greeter.v2, enquanto a v1 continua atendendo.
Essa convenção mantém organizados os módulos gerados do Rust: greeter::v1 e greeter::v2 coexistem.
package greeter.v1;
// later, a parallel file:
// package greeter.v2;Regras de Compatibilidade dos Campos
Adicionar um novo campo com um número inédito é compatível com versões anteriores; clientes antigos o ignoram. Remover um campo é arriscado, a menos que você reserve seu número e nome.
A reserva impede que alguém reutilize um número de campo aposentado e corrompa a decodificação.
message User {
reserved 3, 5;
reserved "legacy_token";
string id = 1;
string email = 2;
}Verificação Rápida
Teste sua compreensão das definições de serviços do proto3.
Recapitulação
Você definiu serviços e mensagens no proto3: números de campo estáveis, mapeamentos de escalares para Rust, enumerações, campos repetidos e aninhados, os quatro formatos de RPC, tipos conhecidos e versionamento por meio de pacotes.
Em seguida, você transformará essas definições em código Rust com tonic-build.
Perguntas Frequentes
A aula “Definições de Protobuf e serviços” é grátis?
Sim — o texto completo de “Definições de Protobuf e serviços” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Learn Rust Coding, atualize para CoddyKit PRO. O curso de Learn Rust Coding inclui 4 aulas no total.
O que vou aprender em “Definições de Protobuf e serviços”?
Descreva sua API em proto. Você pratica Learn Rust Coding com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Learn Rust Coding?
Nenhuma experiência prévia é necessária. Learn Rust Coding no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.
Quanto tempo leva a aula “Definições de Protobuf e serviços”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Learn Rust Coding?
Sim. Cada aula de Learn Rust Coding inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Definições de Protobuf e serviços
- Gerando código com tonic-build
- Implementando um servidor gRPC
- Chamando a partir de um cliente gRPC