Estrutura do arquivo

As APIs gRPC precisam ser definidas em arquivos .proto usando o IDL proto3.

A estrutura de arquivo precisa colocar definições de nível superior e mais importantes antes de itens de nível inferior e menos importantes. Em cada arquivo proto, as seções aplicáveis precisam estar na seguinte ordem:

Copyright e aviso de licença, se necessário.
Declarações proto syntax, package, import e option nesse pedido.
A documentação da visão geral da API que prepara os leitores para o restante do arquivo.
As definições de proto da API service, em ordem decrescente de importância.
As definições message de solicitação e resposta RPC, na mesma ordem dos métodos correspondentes. Cada mensagem de solicitação precisa preceder a mensagem de resposta correspondente, se houver.
As definições de recurso message. Um recurso pai precisa ser definido antes dos recursos filho.

Se um único arquivo proto contém toda a superfície da API, ele deve ter o nome da API:

API	Proto
`Library`	`library.proto`
`Calendar`	`calendar.proto`

Grandes arquivos .proto podem ser divididos em vários arquivos. Os serviços, as mensagens de recursos e as mensagens de solicitação/resposta serão movidos para arquivos separados conforme necessário.

Recomendamos um arquivo por serviço com a solicitação e as respostas correspondentes. Considere nomear este arquivo como <enclosed service name>.proto. Para arquivos proto apenas com recursos, considere nomear esse arquivo simplesmente como resources.proto.

Nomes de arquivos proto

Os nomes do arquivo Proto precisam usar nomes_em_letra_minúscula_separados_por_sublinhado e precisam usar a extensão .proto. Exemplo: service_controller.proto.

Opções de proto

Para gerar bibliotecas de cliente consistentes em diferentes APIs, os desenvolvedores de API precisam usar opções proto consistentes nos arquivos .proto. As definições de API em conformidade com este guia precisam usar as seguintes opções de proto no nível do arquivo:

syntax = "proto3";

// The package name should start with the company name and end with
// the major version.
package google.abc.xyz.v1;

// This option specifies the namespace to be used in C# code. This defaults
// to the PascalCased version of the proto package, which is fine if the
// package name consists of single-word segments.
// For example, a package name of "google.shopping.pets.v1" would use a C#
// namespace of "Google.Shopping.Pets.V1".
// However, if any segment of a package name consists of multiple words,
// this option needs to be specified to avoid only the first word being
// capitalized. For example, a Google Pet Store API might have a package name of
// "google.shopping.petstore.v1", which would mean a C# namespace of
// "Google.Shopping.Petstore.V1". Instead, the option should be used to
// capitalize it properly as "Google.Shopping.PetStore.V1".
//
// For more detail on C#/.NET capitalization rules, see the [Framework Design
// Guidelines](https://msdn.microsoft.com/en-us/library/ms229043).
//
// One corner-case of capitalization: while acronyms are generally
// PascalCased (e.g. Http), two-letter acronyms are normally all in capitals,
// e.g. `IOStream` and `OSVersion`, not `IoStream` and `OsVersion`. However,
// in APIs this should be used carefully, as protoc doesn't know which words
// are abbreviations and which aren't: it would introduce inconsistency to have
// a namespace of (say) `OSLogin` but then a class called `OsDetails` generated
// from a message of the same name. Unless you can be certain that the acronym
// won't crop up in a message or field name, it's safest to stick to regular
// PascalCase.
//
// For pre-releases, the Alpha/Beta should also be capitalized, so "V1Beta1"
// rather than "V1beta1" for example.
option csharp_namespace = "Google.Abc.Xyz.V1";

// This option lets the proto compiler generate Java code inside the package
// name (see below) instead of inside an outer class. It creates a simpler
// developer experience by reducing one-level of name nesting and be
// consistent with most programming languages that don't support outer classes.
option java_multiple_files = true;

// The Java outer classname should be the filename in UpperCamelCase. This
// class is only used to hold proto descriptor, so developers don't need to
// work with it directly.
option java_outer_classname = "XyzProto";

// The Java package name must be proto package name with proper prefix.
option java_package = "com.google.abc.xyz.v1";

// A reasonable prefix for the Objective-C symbols generated from the package.
// It should at a minimum be 3 characters long, all uppercase, and convention
// is to use an abbreviation of the package name. Something short, but
// hopefully unique enough to not conflict with things that may come along in
// the future. 'GPB' is reserved for the protocol buffer implementation itself.
option objc_class_prefix = "GABCX";

// This option specifies the namespace to be used in PHP code. This defaults
// to the PascalCased version of the proto package, which is fine if the
// package name consists of single-word segments.
// For example, a package name of "google.shopping.pets.v1" would use a PHP
// namespace of "Google\\Shopping\\Pets\\V1".
// However, if any segment of a package name consists of multiple words,
// this option needs to be specified to avoid only the first word being
// capitalized. For example, a Google Pet Store API might have a package name of
// "google.shopping.petstore.v1", which would mean a PHP namespace of
// "Google\\Shopping\\Petstore\\V1". Instead, the option should be used to
// capitalize it properly as "Google\\Shopping\\PetStore\\V1".
//
// For pre-releases, the Alpha/Beta should not be capitalized, so "V1beta1"
// rather than "V1Beta1" for example. Note that this is different from the
// capitalization used in the csharp_namespace option for pre-releases.
option php_namespace = "Google\\Abc\\Xyz\\V1";

Estrutura do diretório

Glossário