Dateistruktur

gRPC-APIs sollten in .proto-Dateien mit der IDL proto3 definiert werden.

In der Dateistruktur müssen höhere Ebenen und wichtigere Definitionen den unteren Ebenen und weniger wichtigen Elementen vorangestellt werden. Die anwendbaren Abschnitte sollten in jeder Proto-Datei in dieser Reihenfolge aufgeführt werden:

  • Urheberrecht- und Lizenzvermerk, falls erforderlich.
  • Proto-Anweisungen syntax, package, import und option in dieser Reihenfolge.
  • Die API-Übersichtsdokumentation, die einen Überblick über die Datei bietet.
  • Die API-Proto service-Definitionen in absteigender Reihenfolge ihrer Bedeutung.
  • Die message-Definitionen von RPC-Anfragen und -Antworten in derselben Reihenfolge wie die entsprechenden Methoden. Jede Anfragenachricht muss ihrer jeweiligen Antwortnachricht vorangestellt sein.
  • Die message-Definitionen von Ressourcen. Eine übergeordnete Ressource muss vor ihren untergeordneten Ressourcen definiert werden.

Wenn eine einzelne Proto-Datei die gesamte API-Oberfläche enthält, sollte sie nach der API benannt werden:

API Proto
Library library.proto
Calendar calendar.proto

Große .proto-Dateien können in mehrere Dateien aufgeteilt werden. Die Dienste, Ressourcennachrichten und Anfrage-/Antwortnachrichten sollten in separate Dateien verschoben werden.

Wir empfehlen eine Datei pro Dienst mit der entsprechenden Anfrage und den Antworten. Sie sollten diese Datei <enclosed service name>.proto nennen. Für Proto-Dateien, die nur Ressourcen enthalten, sollten Sie diese Datei einfach resources.proto nennen.

Proto-Dateinamen

Proto-Dateinamen sollten mit durch Unterstriche getrennte Namen in Kleinbuchstaben benannt werden und müssen die Erweiterung .proto haben. Beispiel: service_controller.proto.

Proto-Optionen

Zum Generieren konsistenter Client-Bibliotheken über verschiedene APIs hinweg müssen API-Entwickler konsistente Proto-Optionen in ihren .proto-Dateien verwenden. API-Definitionen, die diesem Leitfaden entsprechen, müssen die folgenden Proto-Optionen auf Dateiebene verwenden:

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