文件结构

gRPC APIs 应该 在后缀是.proto的文件中用proto3 交互式数据语言定义。

文件结构 必须 坚持较高等级和更重要的定义在前，较低等级和重要性较低的定义在后的原则。在每一个proto文件中，可以接受的章节顺序如下所示:

• 版权和许可声明(如果需要的话)
• Proto syntax，package，option和import的声明(注意顺序)
• API 概述，方便读者快速了解文章的剩余内容
• API proto 服务定义，按照重要顺序从高到低
• 资源消息体定义，父级必须在其子级的前面定义
• RPC请求和响应的消息定义，保持相关方法的先后顺序。每个请求消息必须在相应的响应消息(如果有的话)前面定义

如果一个单一的proto文件包含了所有的API定义,应该以API名称作为文件名,例如:

大型的.proto文件可以分割成多个小文件。可以将服务、资源消息和请求/响应消息，分别保存在不同的文件中。

如果一个proto文件里既有服务，又有相关的请求/响应，那么我们建议该文件名是 <包含服务名的名称>.proto;
如果一个proto文件里面只有资源，那么可以考虑简单的命名该文件为resources.proto.

Proto 文件名

Proto 文件名 应该 小写,下划线分隔,并且 必须 使用 ·proto 作为后缀名。 例如: service_controller.proto。

Proto 选项

为了保证跨不同API的客户端库的一致性，API开发者 必须 在.proto文件中使用一致的proto选项(option)。符合本文规范的API定义 必须 使用如下的文件级别的proto选项:

syntax = "proto3";
// package名称应该是公司名开头,主版本号结尾
package google.abc.xyz.v1;
// 本选项描述了C#语言中使用的命名空间。
// proto包的名称默认是驼峰式命名规则,由多个单一单词构成的段组成，每个段之间用'.'分隔。
// 例如，一个包名称是"google.shopping.pets.v1",就会使用C#的命名空间 "Google.Shopping.Pets.V1".
// 然而，如果构成包名称的任意一个段是由多个单词构成的，要避免只有第一个单词的首字母大写。
// 例如，假设一个谷歌宠物商店API的包名称是"google.shopping.petstore.v1",
// 对应的C#风格的命名空间就是"Google.Shopping.Petstore.V1".
// 但是， 正确的大写规则应该是"Google.Shopping.PetStore.V1"
// 更多的C#/.NET大写规则细节，请参考[Framework Design Guidelines](https://msdn.microsoft.com/en-us/library/ms229043)
option csharp_namespace = "Google.Abc.Xyz.V1";
// 本选项让proto编译器在包名(参考下一选项)内部产生Java代码，而不是在一个外部类以内。
// 通过减少一层的命名嵌套，提供了一种更简单的开发体验，这与其他大多数不支持外部类的编程语言保持一致.
option java_multiple_files = true;
// Java外部类的名称应该符合驼峰命名法则. 该类只是用来持有proto的描述符，所以开发者不需要直接与它打交道。
option java_outer_classname = "XyzProto";
// Java包名必须是proto包名加上适当的前缀
option java_package = "com.google.abc.xyz.v1";
// 给包提供一个能够合理标识Objective-C的前缀。
// 至少3个字母,全部大写，一般都是包名称的缩写。
// 短小，但是具有一定独特性，预期不会在将来产生冲突。
// 'GPB'是谷歌protocol buffer实现的保留字。
option objc_class_prefix = "GABCX";