gRPC in ASP.NET Core 3.0 -- Protocol Buffer（1）
開發(fā)環(huán)境：
IDE: VSCode
VSCode的擴展插件：vscode-proto3和Clang-Format這兩個擴展
Windows還需要安裝Clang，Windows 64位系統(tǒng)的地址如下：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）的類型
字段的名稱
字段的數(shù)值（也叫Tag），這個數(shù)字是唯一的。它們是用來在信息格式里識別你的字段的，一旦該類型被使用了，那么這個數(shù)字就不要再改變了。
01
標量類型
數(shù)值型：數(shù)值型有很多種形式：double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64。根據(jù)需要選擇對應(yīng)的數(shù)值類型。
布爾型：bool型可以有True和False兩個值。
字符串：string表示任意長度的文本，但是它必須包含的是UTF-8編碼或7位ASCII的文本，長度不可超過232。
?字節(jié)型：bytes可表示任意的byte數(shù)組序列，但是長度也不可以超過232 ?，最后是由你來決定如何解釋這些bytes。例如你可以使用這個類型來表示一個圖片。
做個例子
可以自己做一個例子，需求是這樣的：這個信息表示的是一個人Person，使用proto3語法，字段如下：ID，姓名，身高，體重，頭像，電子郵件，郵件是否已驗證。
這個應(yīng)該沒有什么難度，不過要注意一下別忘記標點符號。
02
關(guān)于字段
字段的數(shù)值（Tag）
? ? ? 在Protocol Buffers里面，字段的名其實沒那么重要，但是寫C#代碼的時候，字段名還是很重要的。
對于protobuf來說，這個tag是更為重要的。
? ? ? 可以使用的最小的tag數(shù)值是1，最大值是229 - 1, 或者 536,870,911。但是你不可以使用19000到19999之間的數(shù)，這部分數(shù)是保留的。
? ? ? 還有一點值得注意的是：
? ? ? 從1到15的Tag數(shù)只占用1個字節(jié)的空間，所以它們應(yīng)該被用在頻繁使用的字段上。而從16到2047，則占用兩個字節(jié)，它們可以用在不頻繁使用的字段上。
字段規(guī)則
? ? ? protobuf的字段必須滿足以下兩個規(guī)則之一：
單數(shù)字段（Singular）
? ? ? 大概意思就是指這個字段只能出現(xiàn)0或1次（不能超過一次），這也是proto3的默認字段規(guī)則。
重復字段（Repeated）
? ? ? 與singular相對的就是repeated。如果你想做一個list或數(shù)組的話，你可以使用重復字段這個概念。這個list可以有任何數(shù)量（包括0）的元素。它里面的值的順序?qū)玫奖Ａ簟?/p>
Repeated Fields 例子
? ? ? 還是使用前面的Person這個例子，我們在里面添加一個repeated字段（電話號碼）：
? ? ? 就是在前面加上repeated這個關(guān)鍵字即可。
? ? ? 在proto3里面，標量類型的repeated字段采用的是packed編碼。
注釋
? ? ? proto文件里可以添加注釋。它們通常被當作你定義的這些消息的文檔。
? ? ? 注釋很簡單，還是兩種形式，直接看代碼就明白了：
保留的字段
? ? ? 保留的字段如果你對你定義的消息類型進行了更新，例如刪除某個字段或者注釋掉某個字段，那么其它開發(fā)者在以后更新這個消息類型的時候可能會重新使用被你刪除/注釋掉的字段的數(shù)值（tag）。如果以后還需要使用這個消息類型的老版本的proto文件，那么這將會引起嚴重的問題，例如數(shù)據(jù)損壞、隱私漏洞等等。
? ? ? 那么一種避免此類事情發(fā)生的解決辦法就是將你刪除/注釋掉的這些字段的數(shù)值（或/并且包括字段名，因為字段名可引起JSON序列化的問題）標記為reserved，如果其他人再使用這個數(shù)值作為字段標識符，那么編譯器就會有錯誤提示：
? ? ? 注意，不可以把reserved數(shù)值和字段名放在同一個reserved語句里。
字段的默認值
當消息被解析的時候，如果編碼的消息里不含有特定的一個singular元素，那么在被解析對象里相應(yīng)的字段就會被設(shè)為默認值。
常用類型的默認值如下：
string：空字符串
bytes：空的byte數(shù)組
bool：false
數(shù)值型：0
枚舉enum：枚舉里定義的第一個枚舉值，值必須是0
repeated：通常是相應(yīng)開發(fā)語言里的空list
還有個消息類型的字段，它的默認值和開發(fā)語言有關(guān)，這個以后再說。
03
枚舉
? ? ? 之前說了，枚舉里面定義的第一個值就是這個枚舉的默認值。
? ? ? Enum的tag必須從0開始，所以0就是枚舉的數(shù)值默認值。
繼續(xù)上個例子
? ? ? 我們對Person添加一個枚舉類型的字段：性別 Gender：
? ? ? 首先需要定義枚舉類型，這里定義了一個枚舉，名稱是Gender，里面有3個值，默認值是NOT_SPECIFIED，數(shù)值默認值就是0。
? ? ? 然后使用這個枚舉類型定義了一個字段，名稱為gender，tag數(shù)為10。
為枚舉值起別名
? ? ? 枚舉值是可以起別名的，起別名的作用就是允許兩個枚舉值擁有同一個數(shù)值。
? ? ? 要想起別名，首先需要設(shè)置allow_alias這個option為true：
? ? ? 然后我們?yōu)镕EMALE這個枚舉值起了一個別名叫做WOMAN，它們的數(shù)值是一樣的。同樣的MAN是MALE的數(shù)值也是一樣的。
? ? ? 枚舉里面的常量的值必須不能超過32位整型的數(shù)值，不建議使用負數(shù)。
? ? ? 枚舉可以定義在message里面，也可以在外邊單獨定義以便復用。如果另一個消息想使用Person里面這個Gender枚舉，那么可以使用Person.Gender這種形式。
? ? ? 針對枚舉值被刪除/注釋掉這種情況，它也可以使用reserved：
數(shù)值和常量名也必須分開使用兩個reserved語句。
其中max表示可能的最大的值。
今天先到這。。
.NET社區(qū)新聞，深度好文，歡迎訪問公眾號文章匯總?http://www.csharpkit.com?
總結(jié)
以上是生活随笔為你收集整理的gRPC in ASP.NET Core 3.0 -- Protocol Buffer（1）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 小白开学Asp.Net Core 《十》
- 下一篇： ASP.NET Core Web Api