Estructura de archivos

Las API de gRPC deben definirse en los archivos .proto con IDL de proto3.

La estructura del archivo debe colocar definiciones de nivel superior y más importantes antes de elementos de nivel inferior y menos importantes. En cada archivo proto, las secciones aplicables deben estar en el orden siguiente:

Derechos de autor y aviso de licencia si es necesario.
Propaga declaraciones syntax, package, import y option en ese orden.
La documentación sobre la descripción general de la API que prepara a los lectores para el resto del archivo.
Las definiciones service de proto de la API, en orden descendente de importancia.
Las definiciones message de solicitud y respuesta de RPC, en el mismo orden que los métodos correspondientes. Cada mensaje de solicitud debe preceder a su mensaje de respuesta correspondiente, si lo hubiera.
Las definiciones de message del recurso Un recurso superior se debe definir antes de que sus recursos secundarios.

Si un solo archivo proto contiene toda la superficie de la API, debe llevar el nombre de la API:

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

Los archivos .proto grandes se pueden dividir en varios archivos. Los servicios, los mensajes de recursos y los mensajes de solicitud y respuesta se deben mover a archivos distintos según sea necesario.

Recomendamos usar un archivo por servicio con sus solicitudes y respuestas correspondientes. Te recomendamos asignarle el nombre <enclosed service name>.proto a este archivo. Para los archivos proto que solo incluyen recursos, considera nombrar este archivo simplemente como resources.proto.

Nombres de archivos proto

Los nombres de los archivos proto deben usar nombres_en_minúscula_separados_por_guiones_bajos y deben usar la extensión .proto. Por ejemplo: service_controller.proto.

Opciones Proto

Para generar bibliotecas cliente coherentes en las diferentes API, los desarrolladores de la API deben usar opciones proto coherentes en sus archivos .proto. Las definiciones de API que se apegan a esta guía deben usar las siguientes opciones proto a nivel de archivo:

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";

Estructura de directorios

Glosario