Struttura dei file

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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

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

  • Copyright e avviso di licenza, se necessario.
  • Istruzioni relative a syntax, package, import e option dell'ordine in questione.
  • La documentazione panoramica dell'API che prepara i lettori per il resto del file.
  • Le definizioni dei protocolli service dell'API, in ordine decrescente di importanza.
  • Le definizioni message di richiesta e risposta RPC, nello stesso ordine dei metodi corrispondenti. Ogni messaggio di richiesta deve precedere l'eventuale messaggio di risposta corrispondente.
  • 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 essere denominato con 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, in base alle esigenze.

Consigliamo un file per servizio con richieste e risposte corrispondenti. Potresti assegnare un nome a questo file <enclosed service name>.proto. Per i file di protocollo con sole risorse, può essere opportuno denominare questo file come resources.proto.

Nomi file protocollo

I nomi di file di protocollo devono utilizzare caratteri in basso_case_underscore_separate_names e devono utilizzare l'estensione .proto. Ad esempio: service_controller.proto.

Opzioni protocollo

Per generare librerie client coerenti tra le diverse API, gli sviluppatori di API devono utilizzare opzioni di protocollo coerenti nei propri file .proto. Le definizioni di 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";