開發環境：

• IDE: VSCode

• VSCode的擴展插件：vscode-proto3和Clang-Format這兩個擴展

• Windows還需要安裝Clang，Windows 64位系統的地址如下：Clang for Windows (64-bit)(http://llvm.org/releases/3.7.0/LLVM-3.7.0-win64.exe)；Mac：brew install clang-format 。

  
  

第一個例子

這行代碼表示我們使用的是語法是proto3，之前還有一個proto2；如果你不寫這一行，那么protocol buffer編譯器會認為你采用的是proto2。這個必須是文件的第一個非空非注釋行。

這里是定義了一個消息名稱為FirstMessage，類型是message。它里面定義了三個字段，它們都是標量類型（Scalar Type），你也可以定義復合類型，這個以后再說。

是指字段（Field）的類型

字段的名稱

字段的數值（也叫Tag），這個數字是唯一的。它們是用來在信息格式里識別你的字段的，一旦該類型被使用了，那么這個數字就不要再改變了。

01

標量類型

• 數值型：數值型有很多種形式：double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64。根據需要選擇對應的數值類型。

• 布爾型：bool型可以有True和False兩個值。

• 字符串：string表示任意長度的文本，但是它必須包含的是UTF-8編碼或7位ASCII的文本，長度不可超過232。

• ?字節型：bytes可表示任意的byte數組序列，但是長度也不可以超過232 ?，最后是由你來決定如何解釋這些bytes。例如你可以使用這個類型來表示一個圖片。

  
  

做個例子

可以自己做一個例子，需求是這樣的：這個信息表示的是一個人Person，使用proto3語法，字段如下：ID，姓名，身高，體重，頭像，電子郵件，郵件是否已驗證。

這個應該沒有什么難度，不過要注意一下別忘記標點符號。

02

關于字段

字段的數值（Tag）

? ? ? 在Protocol Buffers里面，字段的名其實沒那么重要，但是寫C#代碼的時候，字段名還是很重要的。

對于protobuf來說，這個tag是更為重要的。

? ? ? 可以使用的最小的tag數值是1，最大值是229 - 1, 或者 536,870,911。但是你不可以使用19000到19999之間的數，這部分數是保留的。

? ? ? 還有一點值得注意的是：

? ? ? 從1到15的Tag數只占用1個字節的空間，所以它們應該被用在頻繁使用的字段上。而從16到2047，則占用兩個字節，它們可以用在不頻繁使用的字段上。

字段規則

? ? ? protobuf的字段必須滿足以下兩個規則之一：

單數字段（Singular）

? ? ? 大概意思就是指這個字段只能出現0或1次（不能超過一次），這也是proto3的默認字段規則。

重復字段（Repeated）

? ? ? 與singular相對的就是repeated。如果你想做一個list或數組的話，你可以使用重復字段這個概念。這個list可以有任何數量（包括0）的元素。它里面的值的順序將會得到保留。

Repeated Fields 例子

? ? ? 還是使用前面的Person這個例子，我們在里面添加一個repeated字段（電話號碼）：

? ? ? 就是在前面加上repeated這個關鍵字即可。

? ? ? 在proto3里面，標量類型的repeated字段采用的是packed編碼。

注釋

? ? ? proto文件里可以添加注釋。它們通常被當作你定義的這些消息的文檔。

? ? ? 注釋很簡單，還是兩種形式，直接看代碼就明白了：

保留的字段

? ? ? 保留的字段如果你對你定義的消息類型進行了更新，例如刪除某個字段或者注釋掉某個字段，那么其它開發者在以后更新這個消息類型的時候可能會重新使用被你刪除/注釋掉的字段的數值（tag）。如果以后還需要使用這個消息類型的老版本的proto文件，那么這將會引起嚴重的問題，例如數據損壞、隱私漏洞等等。

? ? ? 那么一種避免此類事情發生的解決辦法就是將你刪除/注釋掉的這些字段的數值（或/并且包括字段名，因為字段名可引起JSON序列化的問題）標記為reserved，如果其他人再使用這個數值作為字段標識符，那么編譯器就會有錯誤提示：

? ? ? 注意，不可以把reserved數值和字段名放在同一個reserved語句里。

字段的默認值

當消息被解析的時候，如果編碼的消息里不含有特定的一個singular元素，那么在被解析對象里相應的字段就會被設為默認值。

常用類型的默認值如下：

• string：空字符串

• bytes：空的byte數組

• bool：false

• 數值型：0

• 枚舉enum：枚舉里定義的第一個枚舉值，值必須是0

• repeated：通常是相應開發語言里的空list

• 還有個消息類型的字段，它的默認值和開發語言有關，這個以后再說。

03

枚舉

? ? ? 之前說了，枚舉里面定義的第一個值就是這個枚舉的默認值。

? ? ? Enum的tag必須從0開始，所以0就是枚舉的數值默認值。

繼續上個例子

? ? ? 我們對Person添加一個枚舉類型的字段：性別 Gender：

? ? ? 首先需要定義枚舉類型，這里定義了一個枚舉，名稱是Gender，里面有3個值，默認值是NOT_SPECIFIED，數值默認值就是0。

? ? ? 然后使用這個枚舉類型定義了一個字段，名稱為gender，tag數為10。

為枚舉值起別名

? ? ? 枚舉值是可以起別名的，起別名的作用就是允許兩個枚舉值擁有同一個數值。

? ? ? 要想起別名，首先需要設置allow_alias這個option為true：

? ? ? 然后我們為FEMALE這個枚舉值起了一個別名叫做WOMAN，它們的數值是一樣的。同樣的MAN是MALE的數值也是一樣的。

? ? ? 枚舉里面的常量的值必須不能超過32位整型的數值，不建議使用負數。

? ? ? 枚舉可以定義在message里面，也可以在外邊單獨定義以便復用。如果另一個消息想使用Person里面這個Gender枚舉，那么可以使用Person.Gender這種形式。

? ? ? 針對枚舉值被刪除/注釋掉這種情況，它也可以使用reserved：

數值和常量名也必須分開使用兩個reserved語句。

其中max表示可能的最大的值。

今天先到這。。

---

.NET社區新聞，深度好文，歡迎訪問公眾號文章匯總?http://www.csharpkit.com?

總結

以上是生活随笔為你收集整理的gRPC in ASP.NET Core 3.0 -- Protocol Buffer（1）的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。