Struttura dei file

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

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

• Se necessario, leggi il copyright e la notifica della licenza.
• Istruzioni Proto syntax, package, import e option in questo ordine.
• La documentazione sulla panoramica dell'API che prepara i lettori per il resto del file.
• Le definizioni del protocollo API service, in ordine decrescente di importanza.
• Le definizioni di richiesta e risposta RPC message, nello stesso ordine dei metodi corrispondenti. Ogni messaggio di richiesta deve precedere l'eventuale messaggio di risposta corrispondente.
• La definizione della risorsa message Una risorsa padre deve essere definita prima delle risorse figlio.

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

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 in base alle esigenze.

Consigliamo un file per servizio con le richieste e le risposte corrispondenti. Valuta di denominare questo file <enclosed service name>.proto. Per i file di protocollo con solo risorse, puoi denominare questo file semplicemente come resources.proto.

Nomi file protocollo

I nomi file di protocollo devono utilizzare min_case_underscore_ separata_names e devono utilizzare 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";