Google API 設計指南－文件結構

翻譯自 API Design Guide - File Structure

gRPC API 應該（should） 使用 proto3 在 .proto 文件中定義。

文件中 必須（must） 將高層級和更重要的定義放在其餘項目以前。原型文件 應該（should） 參照下面的順序：

• 版權和許可協議（若是須要）

• 按照 syntax, package, option 和 import 的順序寫的原型

• API 概述文檔

• 以引入順序降序排列的 service 定義

• 資源 message 定義，父資源 必須（must） 在子資源以前定義

• RPC 請求和響應的 message 定義，與對應方法的順序相同。每一個請求信息 必須（must） 在對應響應信息以前（若是有的話）
  <!--more-->

若是一個原型文件包含了全部的 API，那麼它應該以 API 名字命名：

| API | Proto |
| - | - |
| Library | library.proto |
| Calendar | calendar.proto |

若是須要的話，能夠將一個大 .proto 文件中的服務、資源消息、請求/響應消息移動到單獨的文件中。

推薦在單獨的文件中保存單獨的服務和對應的請求響應消息，將文件命名爲 <enclosed service name>.proto。對於只有資源的原型文件，可將它命令爲 resources.proto。

proto 文件名

proto 文件 應該（should） 以小寫字母下劃線分隔的名字命令，而且 必定（must） 要使用 .proto 作爲後綴。例如：service_controller.proto。

proto option

爲了在不一樣 API 中生成一致的客戶端庫，API 開發者 必須（must） 在 .proto 文件中使用一致的 proto option。參照本指南的 API 定義 必須（must） 使用以下的 option：

syntax = "proto3";

// 包名要以公司名開始，以主版本號結束
package google.abc.xyz.v1;

// 這個 option 表示 namespace 在 C# 中使用。默認使用包名的帕斯卡命名法，當包名由一個
// 單詞的當包名由一個單詞的字段組成時這樣是沒問題的。
// 例如，包名 "google.shopping.pets.v1" 應該使用 "Google.Shopping.Pets.V1" 格式的
// C# namespace。
// 可是若是有多個單詞組成的字段時，這個 option 就須要避免只有首個單詞大寫。
// 例如，Google Pet Store API 的包名能夠是 "google.shopping.petstore.v1"，意味着它
// 對應的 C# namespace 是 "Google.Shopping.Petstore.V1"。由於 option 應該將它改成
// "Google.Shopping.PetStore.V1"。
// 對於 C#/.NET 命名格式的更多信息，請查看[Framework Design Guidelines](https://msdn
// .microsoft.com/en-us/library/ms229043)
option csharp_namespace = "Google.Abc.Xyz.V1";

// 這個 option 容許 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";

查看其餘章節