• 文件结构
    • Proto 文件名
    • Proto 选项

    文件结构

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

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

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

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

    API Proto
    Library library.proto
    Calendar calendar.proto

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

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

    Proto 文件名

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

    Proto 选项

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

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