Les API gRPC doivent être définies dans des fichiers .proto à l’aide du langage de définition d'interface (IDL, Interface Definition Language) proto3.
La structure des fichiers doit placer les définitions de niveau supérieur et plus importantes avant les éléments de niveau inférieur et moins importants. Dans chaque fichier proto, les sections applicables doivent se trouver dans l'ordre suivant :
- Mention du copyright et de la licence si nécessaire.
- Les instructions proto
syntax,package,importetoptiondans cet ordre. - La documentation de présentation de l'API qui prépare les lecteurs pour le reste du fichier.
- Les définitions du
serviceproto de l'API, par ordre décroissant d’importance. - Les définitions de
messagedes requêtes et réponses RPC, dans le même ordre que les méthodes correspondantes. Chaque message de requête doit précéder le message de réponse correspondant, le cas échéant. - Les définitions de
messagede la ressource. Une ressource parente doit être définie avant sa ou ses ressources enfants.
Si un seul fichier proto contient la totalité de la surface de l’API, vous devez le nommer comme l’API :
| API | Proto |
|---|---|
Library |
library.proto |
Calendar |
calendar.proto |
Les fichiers .proto volumineux peuvent être divisés en plusieurs fichiers. Les messages des services, des ressources, et les messages de requête/réponse doivent être déplacés dans des fichiers séparés, le cas échéant.
Nous recommandons un fichier par service avec la requête et les réponses correspondantes. Pensez à nommer ce fichier <enclosed service name>.proto.
Pour les fichiers proto ne comportant que des ressources, envisagez de nommer ce fichier resources.proto tout simplement.
Noms de fichiers proto
Les noms de fichiers proto doivent comporter des noms_séparés_par_des_tirets_bas_en_minuscules et doivent utiliser l'extension .proto. Exemple : service_controller.proto
Options proto
Afin de générer des bibliothèques clientes cohérentes dans différentes API, les développeurs d'API doivent utiliser des options proto cohérentes dans leurs fichiers .proto. Les définitions d'API conformes à ce guide doivent utiliser les options proto de niveau fichier suivantes :
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";