在 Golang 中使用 Protobuf

KevinYan發表於2019-12-05
Golang

本教程使用proto3版本的protocol buffer語言，提供了一個基本的在Go程式中使用protocol buffer的介紹。透過建立一個簡單的示例應用程式，向你展示如何

  • 在.proto檔案中定義訊息格式。
  • 使用protoc編譯器編譯生成Go程式碼。
  • 使用Go的protocol buffer API讀寫訊息。

它不是一個全面的在Go中使用protocol buffer的指南，更詳細的參考資訊請檢視前面的兩個教程。

Protobuf語言指南

Protobuf生成Go程式碼指南

為什麼使用protocol buffer

我們將要使用的示例是一個非常簡單的“地址簿”應用程式，可以在檔案中讀取和寫入人員的聯絡人詳細資訊。地址簿中的每個人都有姓名，ID，電子郵件地址和聯絡電話號碼。

如何序列化和檢索這樣的結構化資料？有幾種方法可以解決這個問題：

  • 使用gobs（Go中自定義的序列化編碼格式）序列化Go資料結構。這是Go特定環境中的一個很好的解決方案，但如果需要與為其他平臺編寫的應用程式共享資料，它將無法正常工作。
  • 可以發明一種特殊的方法將資料項編碼為單個字串 - 例如將4個整數編碼為“12：3：-23：67”。這是一種簡單而靈活的方法，雖然它確實需要編寫一次性編碼和解析程式碼，並且解析會產生較小的執行時成本。這最適合編碼非常簡單的資料。
  • 將資料序列化為XML。這種方法非常有吸引力，因為XML（有點）是人類可讀懂的，並且有許多語言都有相應的類庫。如果您想與其他應用程式/專案共享資料，這可能是一個不錯的選擇。然而，XML是眾所周知的空間密集型，並且編碼/解碼它會對應用程式造成巨大的效能損失。此外，導航XML DOM樹比通常在類中導航簡單欄位要複雜得多。

protocol buffer是靈活，高效，自動化的解決方案，可以解決這個問題。使用protocol buffer，您可以編寫要儲存的資料結構的.proto描述。由此，protocol buffer編譯器會建立一個類，該類使用有效的二進位制格式實現協議緩衝區資料的自動編碼和解析。生成的類會為構成protocol buffer的欄位提供getter和setter，並負責將protocol buffer作為一個單元讀取和寫入的細節。重要的是，protocol buffer格式支援隨著時間的推移擴充套件格式的想法，使得程式碼仍然可以讀取使用舊格式編碼的資料。

獲得示例程式

示例是一組用於管理地址簿資料檔案的命令列應用程式，使用protocol buffer進行編碼。命令add_person_go向資料檔案新增新條目。命令list_people_go解析資料檔案並將資料列印到控制檯。

下載這些檔案到你的專案目錄中：

定義協議格式

要建立地址簿應用程式，您需要從.proto檔案開始。 .proto檔案中的定義很簡單：為要序列化的每個資料結構定義訊息，然後為訊息中的每個欄位指定名稱和型別。在我們的示例中，定義訊息的.proto檔案是addressbook.proto。

.proto檔案以包宣告開頭，這有助於防止不同專案之間的命名衝突。

syntax = "proto3";
package tutorial;

import "google/protobuf/timestamp.proto";

在Go中，protocol buffer的包名稱用作Go包，除非您指定了go_package。即使你確實提供了go_package，你仍然應該在.proto檔案中定義一個包名，以避免在Protocol Buffers名稱空間和非Go語言中發生名稱衝突。

接下來，是訊息定義。訊息只是包含一組型別欄位的聚合。許多標準的簡單資料型別都可用作欄位型別，包括bool，int32，float，double和string。您還可以使用其他訊息型別作為欄位型別，為訊息新增更多結構。

message Person {
  string name = 1;
  int32 id = 2;  // Unique ID number for this person.
  string email = 3;

  enum PhoneType {
    MOBILE = 0;
    HOME = 1;
    WORK = 2;
  }

  message PhoneNumber {
    string number = 1;
    PhoneType type = 2;
  }

  repeated PhoneNumber phones = 4;

  google.protobuf.Timestamp last_updated = 5;
}

// Our address book file is just one of these.
message AddressBook {
  repeated Person people = 1;
}

在上面的示例中，Person訊息包含PhoneNumber訊息，而AddressBook訊息包含Person訊息。您甚至可以定義巢狀在其他訊息中的訊息型別 -​​ 如您所見，PhoneNumber型別在Person中定義。如果您希望其中一個欄位值的取值範圍是預定義的值列表中的值，還可以定義列舉型別 - 此處你要指定電話號碼可以是MOBILE，HOME或WORK之一。

每個元素上的“= 1”，“= 2”標記標識該欄位在二進位制編碼中使用的唯一“標記”。標籤號1-15編碼時比更大編號少需要一個位元組，因此作為最佳化，您可以決定將這些標籤用於常用或重複的元素，將標籤16和更高標籤留給不太常用的可選元素。重複欄位中的每個元素都需要重新編碼標記號，因此重複欄位特別適合此最佳化。

如果未設定欄位值，則使用預設值：數字型別為零，字串為空字串，bools為false。對於嵌入式訊息，預設值始終是訊息的“預設例項”或“原型”，其中沒有設定其欄位。呼叫訪問器以獲取尚未顯式設定的欄位的值始終返回該欄位的預設值。

如果一個欄位是可重複的，該欄位可以重複任意次數（包括零）。重複值的順序將保留在protocol buffer中。將可重複欄位視為變長陣列。

您將在Protobuf語言指南中找到編寫.proto檔案的完整指南 - 包括所有可能的欄位型別。不要去尋找類繼承類似的東西，protocol buffer不支援這些。

編譯protocol buffers

有了.proto後，你需要做的下一件事是生成你需要讀取和寫入AddressBook（以及Person和PhoneNumber）訊息所需的類（Go中是結構體和結構體方法）。為此，你需要在.proto上執行protocol buffer譯器protoc：

  1. 請先確保已經安裝了編譯器protoc

  2. protoc需要安裝外掛才能編譯生成Go程式碼，可以執行如下命令安裝外掛

    go get -u github.com/golang/protobuf/protoc-gen-go

  3. 現在執行編譯器，指定源目錄（應用程式的原始碼所在的位置 - 如果不提​​供值，則使用當前目錄），目標目錄（您希望生成的程式碼在哪裡;通常與$相同） SRC_DIR），以及.proto的路徑。在這種情況下，你...：

    protoc -I=$SRC_DIR --go_out=$DST_DIR $SRC_DIR/addressbook.proto

​ 我們使用的示例go程式碼中匯入編譯後的pb.go檔案的路徑是 pb "github.com/protocolbuffers/protobuf/examples/tutorial" 所以用protoc編譯時使用的目標路徑應該是

protoc --go_out=$GOPATH/src/github.com/protocolbuffers/protobuf/examples/tutorial ./addressbook.proto

$GOPATH/src/github.com/protocolbuffers/protobuf/examples/tutorial目錄需要提前建立好。

Protocol buffer API

生成addressbook.pb.go提供以下有用型別：

  • 擁有有People欄位的AddressBook結構體。
  • 擁有Name，Id，Email和Phones欄位的Person結構體。
  • Person_PhoneNumber結構體，包含Number和Type欄位。
  • 型別Person_PhoneType和為Person.PhoneType列舉中的每個值定義的常量。

可以閱讀更多有關“生成程式碼”指南中生成的內容的詳細資訊，但在大多數情況下，您可以將這些視為完全普通的Go型別。

行動勝千言，下載教程中提供的程式碼，執行上面的編譯命令，去看看生成的addressbook.pb.go中的程式碼吧。

下面是如何建立Person例項的示例:

p := pb.Person{
        Id:    1234,
        Name:  "John Doe",
        Email: "jdoe@example.com",
        Phones: []*pb.Person_PhoneNumber{
                {Number: "555-4321", Type: pb.Person_HOME},
        },
}

在Go中序列化protocol buffer資料

使用protocl buffer目的是序列化你的結構化資料，以便可以在其他地方解析它。在Go中，使用proto庫的Marshal函式來序列化protocol buffer資料。指向訊息的結構體的指標實現了proto.Message介面。呼叫proto.Marshal會返回以其有線格式編碼的protocol buffer。例如，我們在add_person命令中使用此函式：

book := &pb.AddressBook{}
// ...

// Write the new address book back to disk.
out, err := proto.Marshal(book)
if err != nil {
        log.Fatalln("Failed to encode address book:", err)
}
if err := ioutil.WriteFile(fname, out, 0644); err != nil {
        log.Fatalln("Failed to write address book:", err)
}

在Go中解析protocol buffer

要解析編碼訊息，請使用proto庫的Unmarshal函式。呼叫它將buf中的資料解析為protocol buffer，並將結果放在結構體中。因此，要在list_people命令中解析檔案，我們使用：

// Read the existing address book.
in, err := ioutil.ReadFile(fname)
if err != nil {
        log.Fatalln("Error reading file:", err)
}
book := &pb.AddressBook{}
if err := proto.Unmarshal(in, book); err != nil {
        log.Fatalln("Failed to parse address book:", err)
}

執行Go應用程式

  • 命令列中執行go build add_person.go 和 go build list_people.go 會生成兩個二進位制檔案add_person和list_people。
  • 命令列執行 ./add_person ADDRESS_BOOK 程式會在命令列中提示輸入，用命令列的輸入構建地址簿資料然後將資料序列化為protocol buffer儲存到檔案ADDRESS_BOOK中。
  • 命令列執行./list_people 程式會從檔案ADDRESS_BOOK讀取protocol buffer資料，解析到結構體中然後列印出結構體中的Person資料。
本作品採用《CC 協議》，轉載必須註明作者和本文連結
公眾號:網管叨bi叨 | Golang、Laravel、Docker、K8s等學習經驗分享

相關文章