此页面由 Cloud Translation API 翻译。

文件结构

gRPC API 应该使用 proto3 IDL 在 .proto 文件中定义。

文件结构必须将更高级别和更重要的定义置于较低级别和较不重要的项目之前。在每个 proto 文件中，适用的部分应按以下顺序排列：

版权和许可声明（如果需要）。
采用该顺序的 Proto syntax、package、import 和 option 语句。
API 概览文档，为读取器准备文件的其余部分。
按重要性降序排列的 API proto service 定义。
与相应方法采用相同顺序的 RPC 请求和响应 message 定义。每个请求消息必须在其相应的响应消息之前（如果有）。
资源 message 定义。父资源必须在其子资源之前定义。

如果单个 proto 文件包含整个 API 接口，应在 API 之后命名：

API	Proto
`Library`	`library.proto`
`Calendar`	`calendar.proto`

大 .proto 文件可能会拆分为多个文件。应根据需要将服务、资源消息和请求/响应消息移到单独的文件中。

我们建议每个服务及其相应的请求和响应使用一个文件。请考虑将此文件命名为 <enclosed service name>.proto。对于仅包含资源的 proto 文件，请考虑将此文件简单命名为 resources.proto。

Proto 文件名

Proto 文件名应该使用 lower_case_underscore_separated_names，并且必须使用扩展名 .proto。例如：service_controller.proto。

Proto 选项

为了在不同 API 中生成一致的客户端库，API 开发人员必须在其 .proto 文件中使用一致的 proto 选项。符合本指南的 API 定义必须使用以下文件级 proto 选项：

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

目录结构

术语库