Struttura dei file

Le API gRPC devono essere definite in .proto file utilizzando l'IDL proto3.

La struttura del file deve definire le definizioni di livello superiore e più importanti prima degli elementi di livello inferiore e meno importanti. In ogni file di proto, le sezioni applicabili devono essere nel seguente ordine:

• Nota sul copyright e sulla licenza, se necessario.
• Istruzioni di protocollo syntax, package, import e option in questo ordine.
• La documentazione della panoramica dell'API, che prepara i lettori per il resto del file.
• Definizioni del protocollo API service, in ordine di importanza decrescente.
• Le definizioni di message richiesta e risposta RPC, nello stesso ordine dei metodi corrispondenti. Ogni messaggio di richiesta deve precedere il relativo messaggio di risposta, se presente.
• Le definizioni della risorsa message. Una risorsa padre deve essere definita prima delle relative risorse figlio.

Se un singolo file di protocollo contiene l'intera superficie API, deve avere il nome dell'API:

API	Proto
Library	library.proto
Calendar	calendar.proto

I file .proto di grandi dimensioni possono essere suddivisi in più file. I servizi, i messaggi delle risorse e i messaggi di richiesta/risposta devono essere spostati in file separati, se necessario.

Consigliamo di utilizzare un file per servizio con la richiesta e le risposte corrispondenti. Assegna a questo file il nome <enclosed service name>.proto. Per i file proto con solo risorse, valuta la possibilità di assegnare a questo file il nome resources.proto.

Nomi file di protocollo

I nomi dei file di protocollo devono contenereus min_case_underscore_separate_names e devono usare l'estensione .proto. Ad esempio: service_controller.proto.

Opzioni protocollo

Per generare librerie client coerenti tra API diverse, gli sviluppatori di API devono utilizzare opzioni di protocollo coerenti nei file .proto. Le definizioni dell'API conformi a questa guida devono utilizzare le seguenti opzioni di protocollo a livello di file:

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