OBSERVAÇÃO:este site foi descontinuado. O site será desativado após 31 de janeiro de 2023, e o tráfego será redirecionado para o novo site em https://protobuf.dev. Enquanto isso, as atualizações serão feitas apenas para protobuf.dev.

Guia de estilo

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Neste documento, você encontra um guia de estilo para arquivos .proto. Seguindo essas convenções, você vai tornar as definições de mensagem do buffer de protocolo e as classes correspondentes consistentes e fáceis de ler.

Como o estilo do buffer de protocolo evoluiu com o tempo, é provável que você veja arquivos .proto escritos em diferentes convenções ou estilos. Respeite o estilo existente ao modificar esses arquivos. Consistência é fundamental. No entanto, é melhor adotar o melhor estilo atual ao criar um novo arquivo .proto.

Formatação de arquivo padrão

  • Mantenha a linha com 80 caracteres.
  • Use um recuo de dois espaços.
  • Use aspas duplas para strings.

Estrutura do arquivo

Os arquivos precisam ser nomeados como lower_snake_case.proto

Todos os arquivos precisam ser ordenados desta maneira:

  1. Cabeçalho da licença (se aplicável)
  2. Visão geral do arquivo
  3. Sintaxe
  4. Pacote
  5. Importações (classificadas)
  6. Opções de arquivo
  7. Todos os outros

Entrega de pacotes

Os nomes de pacotes precisam estar em letras minúsculas. Os nomes de pacotes precisam ter nomes exclusivos com base no nome do projeto e, possivelmente, no caminho do arquivo que contém as definições de tipo de buffer de protocolo.

Nomes de campos e mensagens

Use CamelCase (com uma letra inicial maiúscula) em nomes de mensagens, por exemplo, SongServerRequest. Use underline_ separados_nomes para nomes de campo (incluindo um dos nomes de campo e extensão), por exemplo, song_name.

message SongServerRequest {
  optional string song_name = 1;
}

O uso dessa convenção de nomenclatura para nomes de campos permite o acesso a:

C++:
  const string& song_name() { ... }
  void set_song_name(const string& x) { ... }

Java:
  public String getSongName() { ... }
  public Builder setSongName(String v) { ... }

Se o nome do campo tiver um número, esse número deverá aparecer depois da letra, e não após o sublinhado. Por exemplo, use song_name1 em vez de song_name_1.

Campos repetidos

Use nomes pluralizados para campos repetidos.

  repeated string keys = 1;
  ...
  repeated MyMessage accounts = 17;

Enums

Use CamelCase (com uma letra inicial maiúscula) para nomes de tipos de enumeração e CAPITALS_WITH_SUBSCORES para nomes de valores:

enum FooBar {
  FOO_BAR_UNSPECIFIED = 0;
  FOO_BAR_FIRST_VALUE = 1;
  FOO_BAR_SECOND_VALUE = 2;
}

Cada valor de enumeração precisa terminar com um ponto e vírgula, não uma vírgula. Prefira prefixar valores de enumeração em vez de circundá-los em uma mensagem. A enumeração de valor zero precisa ter o sufixo UNSPECIFIED, porque um servidor ou aplicativo que receber um valor de enumeração inesperado marcará o campo como não configurado na instância proto. O acessador de campo retornará o valor padrão, que, para os campos de enumeração, é o primeiro valor de enumeração.

Serviços

Se o .proto definir um serviço de RPC, você precisará usar CamelCase (com uma letra inicial maiúscula) em nome do serviço e de qualquer método de RPC:

service FooService {
  rpc GetSomething(GetSomethingRequest) returns (GetSomethingResponse);
  rpc ListSomething(ListSomethingRequest) returns (ListSomethingResponse);
}

O que deve ser evitado

  • Campos obrigatórios (somente para proto2)
  • Grupos (somente para proto2)