樣式指南 Style Guide
前言大綱
protobuf 消息和服務定義是波士頓動力 API 的主要介面定義。定義的一致性使 API 更易於理解和開發。
僅限 Proto3。所有服務和消息只能使用 proto3。這讓我們能夠接觸到盡可能廣泛的目標平台,並提供一致性。
遵循 Google protobuf 樣式指南。他們的樣式指南非常簡單,我們的 API 支持它,但有一些例外。
行長度應為 100 個字符。
縮進應為 4 個空格。
使用“Service”後綴作為服務定義。這使得在生成的代碼中更容易區分服務名稱和消息名稱。
使用 RequestHeader 和 ResponseHeader 作為請求和響應中的第一個字段。這提供了一種收集時序信息、常見錯誤(例如錯誤輸入)和其他常見處理技術的一致方法。存在不同語言的函式庫以簡化對這些的處理。
遵循常見錯誤方法。 gRPC 錯誤用於傳輸級別的問題,例如網絡問題或錯誤的授權令牌 - 這意味著服務實現幾乎總是希望返回 gRPC 狀態正常。內部服務問題——比如沒有設置前置條件——應該在公共 ResponseHeader 中使用 INTERNAL_SERVER_ERROR 和可選的錯誤文本字符串。由於客戶端編程錯誤而導致的格式不正確的請求消息應在公共 ResponseHeader 中使用 INVALID_REQUEST 並帶有可選的錯誤文本字符串。所有其他響應狀態應使用特定於特定 RPC 調用的單獨錯誤代碼,位於公共標頭之外。錯誤消息可以與此特定於調用的錯誤代碼一起報告,但枚舉應該足夠詳細,以便永遠不需要在代碼中解析錯誤消息。公共標頭中的消息字段不應設置為描述特定於調用的錯誤。
時間用 google.protobuf.Timestamp 表示,都在“robot time”。所有時間戳都以機器人的掛鐘為基礎,並使用 Timestamp 對象來表示時間。存在單獨的 TimeSync 服務以保持客戶端和機器人按時同步。
持續時間用 google.protobuf.Duration 表示。使用 Duration 類型明確指定該字段是一個持續時間。
對物理量使用 MKS 單位。使用物理量的 MKS 單位系統與 API 的其餘部分保持一致。角度變量應該是弧度而不是度數。
枚舉Enums 應該在 0 處有一個 UNKNOWN 入口,然後是其他值。當變量未設置時,Proto3 使用 0 枚舉 Enum 值,因此為 UNKNOWN 保留該枚舉值。通常,不應寫入此值,並將其視為讀取錯誤。
枚舉Enums 應該以其 枚舉類型 enum type 作為前綴。例如,如果 UNKNOWN 是枚舉“Status”的一部分,則枚舉值應為 STATUS_UNKNOWN。這支持 Python 行為,其中枚舉值不受枚舉名稱的限制。
為 java_outer_classname 選項使用“Proto”後綴。默認情況下,Java 的 protobuf 編譯器會在文件 foo.proto 包含消息 Foo 時創建 FooOuterClass。指定選項 java_outer_classname = “FooProto”;所以命名原理更容易弄清楚。 Java 生成的代碼
記錄介面和消息。 proto 定義有效地定義了 API 的協議 - 確保記錄每個字段的含義以及它是什麼單位。理想情況下,每個服務也將進行單元測試,並有如何使用它的教程代碼。如果概念上難以理解,還應包括概念文檔。
RPC 預計將快速完成。 RPC 預計會在 1 秒內響應。快速的響應時間讓客戶端能夠將網絡停頓與處理時間區分開來。但是,有時由 RPC 觸發的操作可能需要 1 秒以上才能完成 - 例如為機器人電機供電,或執行計算成本高的操作。
在這些情況下,請使用 PowerService 演示的反饋 RPC 模式。觸發操作(PowerService 案例中的 PowerCommand)的初始 RPC 將快速完成。對初始 RPC 的響應包括是否滿足操作的先決條件,以及如果滿足先決條件的命令 id。然後,客戶端可以使用命令 id 輪詢反饋 RPC(在 PowerService 案例中為 PowerCommandFeedback)以跟踪操作的進度。
套件。除了 Google style guide,我們還有一些關於“package”指令的額外指南:
- 套件都是小寫的。
- 每個套件級別應該是一個字。
- .proto 文件的套件聲明應與其在 protos/ 子目錄中的相對路徑相匹配。這就是 Python 模塊命名空間與遵守套件指令的語言一致的原因。
- 平直一點更好。例如,比 bosdyn.api.robot.spot 更喜歡 bosdyn.api.spot。
- 考慮為消息和服務創建一個新套件,這些套件應該單獨分發和版本控制。 例如,特定機器人的服務可能與核心 API 基礎設施分開打包。
避免在服務定義文件中指定請求/響應消息 - 將它們放入“foo.proto”文件而不是“foo_service.proto”文件中,以簡化構建系統中的依賴關係。
命名消息時考慮套件/命名空間 - bosdyn.api.spot 套件中的消息在其名稱中不需要“Spot”前綴。
留言
張貼留言
Aron阿龍,謝謝您的留言互動!