本教程使用proto3版本的protocol buffer語言,提供了一個基本的在Go程序中使用protocol buffer的介紹。通過創建一個簡單的示例應用程序,向你展示如何
- 在
.proto
文件中定義消息格式。 - 使用protoc編譯器編譯生成Go代碼。
- 使用Go的protocol buffer API讀寫消息。
它不是一個全面的在Go中使用protocol buffer的指南,更詳細的參考信息請查看前面的兩個教程。
爲什麼使用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
解析數據文件並將數據打印到控制檯。
下載這些文件到你的項目目錄中:
- 描述protocol buffer消息格式的
.proto
文件 addressbook.proto - 命令行程序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:
- 請先確保已經安裝了編譯器
protoc
-
protoc需要安裝插件才能編譯生成Go代碼,可以運行如下命令安裝插件
go get -u github.com/golang/protobuf/protoc-gen-go
-
現在運行編譯器,指定源目錄(應用程序的源代碼所在的位置 - 如果不提供值,則使用當前目錄),目標目錄(您希望生成的代碼在哪裏;通常與$相同) 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: "[email protected]",
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
數據。