樣式指南 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”前綴。


參考資料

特色、摘要,Feature、Summary:

關鍵字、標籤,Keyword、Tag:

留言

這個網誌中的熱門文章

Ubuntu 常用指令、分類與簡介

iptables的觀念與使用

網路設定必要參數IP、netmask(遮罩)、Gateway(閘道)、DNS

了解、分析登錄檔 - log

Python 與SQLite 資料庫

Blogger文章排版範本

Pandas 模組

如何撰寫Shell Script

查詢指令或設定 -Linux 線上手冊 - man

下載網頁使用 requests 模組