Design de Esquemas de Protocol Buffers

Esquemas Protobuf são contratos vivos.

Números de campo, tipos de fio e limites de pacote decidem se você pode implantar um novo serviço sem derrubar metade da frota.

Resumo

Mensagens Protobuf são estruturas de dados versionadas definidas em arquivos .proto.

Cada campo tem uma tag numérica permanente.

Clientes e servidores compilados com meses de diferença ainda devem ser capazes de decodificar as cargas úteis uns dos outros.

O design do esquema é design de API: nomes importam para legibilidade, mas números importam para compatibilidade.

Esta página cobre layout de mensagens, oneof, mapas, enums, importações e as regras que o Google documenta para evolução segura.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

syntax = "proto3";
 
package inventory.v1;
 
option go_package = "example.com/inventory/api/inventory/v1;inventoryv1";
 
import "google/protobuf/timestamp.proto";
 
message Item {
  string id = 1;
  string sku = 2;
  int32 quantity = 3;
  google.protobuf.Timestamp updated_at = 4;
 
  oneof status {
    bool in_stock = 5;
    string backorder_note = 6;
  }
 
  map<string, string> attributes = 7;
}

Quando usar isso:

• Definir tipos de requisição/resposta gRPC compartilhados entre geradores Go, Java e outros.
• Modelar variantes opcionais com oneof em vez de flags booleanas paralelas.
• Anexar metadados de chave-valor abertos com campos map.
• Importar tipos bem conhecidos (Timestamp, Duration, Empty) em vez de reinventá-los.

Exemplo de Trabalho

syntax = "proto3";
 
package orders.v1;
 
option go_package = "example.com/orders/api/orders/v1;ordersv1";
 
import "google/protobuf/field_mask.proto";
 
enum OrderState {
  ORDER_STATE_UNSPECIFIED = 0;
  ORDER_STATE_PENDING = 1;
  ORDER_STATE_SHIPPED = 2;
}
 
message Order {
  string id = 1;
  OrderState state = 2;
  repeated LineItem items = 3;
}
 
message LineItem {
  string product_id = 1;
  int32 qty = 2;
}
 
message UpdateOrderRequest {
  Order order = 1;
  google.protobuf.FieldMask update_mask = 2;
}

package main
 
import (
    "fmt"
 
    ordersv1 "example.com/orders/api/orders/v1"
    "google.golang.org/protobuf/types/known/fieldmaskpb"
)
 
func main() {
    req := &ordersv1.UpdateOrderRequest{
        Order: &ordersv1.Order{
            Id:    "ord-1",
            State: ordersv1.OrderState_ORDER_STATE_SHIPPED,
        },
        UpdateMask: &fieldmaskpb.FieldMask{Paths: []string{"state"}},
    }
    fmt.Println(req.GetUpdateMask().GetPaths())
}

O que isso demonstra:

• Enums incluem o valor zero UNSPECIFIED - nunca use zero como um estado de negócio significativo sem documentá-lo.
• repeated mapeia para slices Go; campos ausentes decodificam como nil/vazio, não erros.
• FieldMask expressa atualizações parciais para RPCs no estilo PATCH.
• go_package mantém o código Go gerado em um caminho de importação estável.

Mergulho Profundo

Como Funciona

Protobuf codifica mensagens como trios de tag-comprimento-valor no fio.

O número do campo seleciona o slot; o tipo de fio informa aos decodificadores como analisar os bytes.

Decodificadores ignoram campos desconhecidos, que é a base da compatibilidade retroativa.

Renomear um campo em .proto não altera o formato do fio - apenas o número e o tipo o fazem.

Regras de Campo em Resumo

Use reserved 3, 5; e reserved "legacy_field"; após remoções.

oneof, mapas e mensagens aninhadas

oneof impõe exclusão mútua - apenas um membro está definido.

Em Go, wrappers gerados expõem acessadores no estilo GetInStock() e um tipo de interface para o caso ativo.

Campos map<K,V> se tornam mapas Go; chaves não podem ser mensagens ou floats.

Mantenha valores de mapa como strings ou números simples quando possível para consistência entre linguagens.

Aninhe mensagens para clareza, mas achate quando a mesma estrutura se repete entre RPCs - tipos compartilhados pertencem a common.proto.

Notas de Go

// Prefira construtores para invariantes obrigatórios
order := &ordersv1.Order{
    Id:    id,
    State: ordersv1.OrderState_ORDER_STATE_PENDING,
}
 
// Clone antes de mutar protobufs compartilhados passados entre goroutines
clone := proto.Clone(order).(*ordersv1.Order)

• Structs gerados usam campos de ponteiro para mensagens; verifique nil antes do acesso aninhado ou use getters.
• proto.Marshal / proto.Unmarshal funcionam sem gRPC para cargas úteis de eventos.
• Execute buf lint ou prototool em CI para impor estilo e detecção de quebra de compatibilidade.

Armadilhas

• Reutilizar números de campo - Clientes antigos enviam bytes para o slot errado. Correção: reserve números e nomes permanentemente.
• Alterar int32 para enum - Tipos de fio podem corresponder, mas semânticas divergem. Correção: adicione um novo número de campo para o enum.
• Valor zero de enum como estado real - Não definido e PENDING colidem. Correção: mantenha UNSPECIFIED = 0 e comece os valores de negócio em 1.
• oneof enorme com muitos braços - O código Go gerado incha. Correção: divida variantes em mensagens aninhadas ou RPCs separadas.
• JSON sobre protobuf para configuração - JSON editado manualmente se desvia do .proto. Correção: gere OpenAPI ou use verificações de quebra buf contra o main.
• Mapas dentro de mensagens repetidas - A ordem de serialização é indefinida; não confie na ordem de iteração do mapa em testes.

Alternativas

FAQs

Relacionados

• gRPC em Go: Contratos, Streaming e Performance - por que contratos importam
• Noções Básicas de gRPC - fluxo de trabalho de geração de código
• Códigos de Erro gRPC e Mapeamento de Status - mensagens de detalhe de erro
• Melhores Práticas de gRPC - versionamento de proto em produção
• Tags Struct para JSON, DB e Validação - padrões de serialização do lado Go

Links Externos Relacionados

• Site Oficial do Go / Documentação - Hub principal de documentação.
• Tutoriais Go (Oficial) - Tutoriais oficiais em várias partes.
• pkg.go.dev - Site oficial de documentação e descoberta de pacotes.
• Learning Go (2ª Edição, O'Reilly) - Jon Bodner na O'Reilly.
• The Go Programming Language (ebook) - Donovan & Kernighan.

Versões da Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).