本文轉(zhuǎn)載自微信公眾號「DotNET技術(shù)圈」，作者 Peter Vogel 。轉(zhuǎn)載本文請聯(lián)系DotNET技術(shù)圈公眾號。 

如何在.NET Core中為gRPC服務(wù)設(shè)計消息

使用協(xié)議緩沖區(qū)規(guī)范定義gRPC服務(wù)非常容易，但從需求轉(zhuǎn)換為.NET Core，然后管理服務(wù)的演變時，需要注意幾件事。

創(chuàng)建gRPC服務(wù)的核心是.proto文件，該文件以與語言無關(guān)的格式描述了該服務(wù)。使用.proto文件，Visual Studio可以為您的服務(wù)生成基類(您只需編寫特定于業(yè)務(wù)的代碼)，或者可以生成用于可靠訪問服務(wù)的客戶端類。

.proto文件必須符合Google的協(xié)議緩沖區(qū)規(guī)范(通常稱為ProtoBuf)。原始文件的內(nèi)容使您可以指定服務(wù)的接口。服務(wù)接口由兩部分組成：

• 您的gRPC服務(wù)提供的方法
• 這些方法的參數(shù)和返回值的數(shù)據(jù)結(jié)構(gòu)

您可以使用Protocol Buffers規(guī)范中[1]定義的標(biāo)量類型來構(gòu)建這些數(shù)據(jù)結(jié)構(gòu)(在ProtoBuf中稱為“消息”)?？捎玫念愋桶ú紶栔担址?，字節(jié)數(shù)組和各種數(shù)字類型(浮點型，整數(shù)型和長型)。沒有日期或固定的十進制類型。在接下來的專欄中，我將向您展示如何添加時間戳類型。對于小數(shù)，您可以使用float ...并伴隨著float帶來的精度損失。

如果您要開始一個新項目，則要使用自2016年以來的proto3語法。但是，您必須在.proto文件的第一行“非空”行上明確指定proto3標(biāo)準(zhǔn)。引用規(guī)范[2])，否則將使用proto2規(guī)范解析您的.proto文件。指定您的文件使用proto3看起來像這樣：

syntax = "proto3"; 

消息和C#類

使用proto3規(guī)范，用于客戶信息的消息格式可能如下所示：

message CustomerResponse { 
  int32 custid = 1; 
  string firstName = 2; 
  string lastName = 3; 
  int32 age = 4; 
  fixed32 creditLimit = 5; 
} 

等號后的數(shù)字指定消息中字段的位置，從位置1開始(在我的示例中，firstName將是消息中的第二個字段)。這些數(shù)字在消息中必須是唯一的(即，您不能在同一位置使用兩個字段)。您不必按數(shù)字順序列出字段，但是如果您這樣做的話，則可以更輕松地發(fā)現(xiàn)重復(fù)的字段編號(盡管Visual Studio將發(fā)現(xiàn)任何重復(fù)的編號，并在構(gòu)建應(yīng)用程序時將其報告在“錯誤列表”中)。如果需要，您也可以跳過職位。此定義僅使用奇數(shù)，例如：

message CustomerResponse { 
  int32 custid = 1; 
  string firstName = 3; 
  string lastName = 5; 
} 

在.NET Core中，消息格式被轉(zhuǎn)換為類，每個字段都成為與消息同名的類的屬性。命名這些屬性時，.NET Core還將字段名稱的第一個字符轉(zhuǎn)換為大寫。因此，例如，我上一個示例中的custId字段將成為我代碼中CustomerResponse類上的CustId屬性。

在此過程中，還得刪除字段名稱中的所有下劃線，并且將以下字母大寫(即，Last_name字段名稱變?yōu)長astName屬性)。

該過程還涉及將.NET類型映射到ProtoBuf類型(例如，ProtoBuf int32變?yōu)?NET int，ProtoBuf的int64變?yōu)閘ong，fixed32變?yōu)閡int)，這需要向.NET Core添加一些新類。例如，ProtoBuf支持字節(jié)數(shù)組，其類型為字節(jié)。名為ByteString的新.NET數(shù)據(jù)類型支持該字段類型。要加載ByteString，請使用ByteString類的靜態(tài)CopyFrom方法，并傳遞一個字節(jié)數(shù)組，如下所示：

byte[] bytes = new byte[1000]; 
cr.Valid = ByteString.CopyFrom(bytes); 

要從ByteString檢索字節(jié)數(shù)組，請使用對象的CopyTo方法，并傳遞要將字節(jié)復(fù)制到的數(shù)組和起始位置：

cr.Valid.CopyTo(bytes,0); 

數(shù)組和字典

您也可以使用【repeated】的關(guān)鍵字將集合包括在定義中(在ProtoBuf中，不是集合的字段稱為“單數(shù)”)。如果我的客戶消息需要一組重復(fù)的交易金額，則可以指定如下字段：

message Customer { 
   int32 id = 1; 
   repeated fixed32 transactionAmounts = 4; 

重復(fù)的字段在轉(zhuǎn)換為類的屬性時，也使用新的類型：Google.Protobuf.RepeatedField。例如，我的示例將生成Google.Protobuf.RepeatedField(無符號整數(shù))的屬性。您可以使用{}語法來初始化數(shù)組，如下所示：

CustomerResponse cr = new CustomerResponse 
            { 
                CreditLimit = {10, 15, 100}     
            }; 

您可能更可能使用其各種Add方法將項目放入集合中：

cr.CreditLimit.Add（200）; 

您可以使用LINQ方法(例如First())或按位置訪問RepeatedField中的項目。可以正常工作，例如：

uint tranAmount = cr.CreditLimit [1]; 

ProtoBuf還支持稱為map的Dictionary-type集合，該集合允許您為字典的鍵和值指定類型。我的客戶消息可能會使用“友好名稱”來跟蹤客戶的各種信用卡，以定義一個字典，該字典包含密鑰(“彼得卡”，“我的旅行卡”)和值(信用卡號)的字符串)：

message CustomerResponse { 
  int32 custId = 1; 
  map<string, string> cards = 2; 

有趣的是，在Visual Studio 2019預(yù)覽版中，編輯器不會像其他類型一樣突出顯示map對象(盡管編譯得很好)。

相應(yīng)的屬性將為Google.Protobuf.Collections.MapField類型，您可以通過將其Add方法傳遞給鍵和一個值來加載它，就像其他任何Dictionary一樣。

管理變更

上線后(客戶端開始使用它)更改.proto文件相對容易。例如，您可以將具有新位置編號的字段添加到服務(wù)器端軟件使用的.proto文件中，而不會打擾仍在使用該文件的早期版本的客戶端：客戶端只是忽略未在其.proto文件中列出的字段。

同樣，在相反的情況下(當(dāng)服務(wù)器.proto文件沒有客戶端的.proto字段具有的字段時)，客戶端只會發(fā)現(xiàn)服務(wù)器未發(fā)送的屬性被設(shè)置為其默認(rèn)值。順便說一句，在服務(wù)器的.proto文件中定義的，未在客戶端的.proto文件中定義的字段仍會發(fā)送到客戶端，但是.NET不能提供一種方便的方式來訪問它(至少現(xiàn)在還沒有)。

確實，隨著服務(wù)的發(fā)展和修改其.proto文件，您僅應(yīng)遵守兩個規(guī)則：

• 不要更改現(xiàn)有字段的位置編號
• 不要回收職位編號(即不要用新的字段3替換過時的字段3)

但是，從.proto文件生成的屬性不可為空，因此，如果未將屬性設(shè)置為值，則它將被設(shè)置為其默認(rèn)值。這意味著數(shù)字被設(shè)置為0;數(shù)字被設(shè)置為0。將string設(shè)置為string.Empty(長度為零的字符串);布爾變成虛假的;ByteString屬性默認(rèn)為ByteString對象，其IsEmpty屬性設(shè)置為true;并且RepeatedField和MapField屬性均默認(rèn)為其對應(yīng)的對象，每個對象均不包含任何項目，并且其Count屬性設(shè)置為0。

由于這種行為，存在從服務(wù)的.proto文件中刪除字段并且不更新所有客戶端(或者只是在服務(wù)器上生成響應(yīng)時未在對象上設(shè)置屬性)的危險。危險是客戶端無法區(qū)分未使用的字段和已設(shè)置為其默認(rèn)值的屬性之間的區(qū)別。如果將我的客戶的有效屬性設(shè)置為false，則客戶端將無法確定客戶是否無效或服務(wù)器是否不再生成該字段。

您可能需要考慮將屬性初始化為某個“不合理的”值(例如，數(shù)字為-1)，以便客戶端可以區(qū)分設(shè)置為默認(rèn)值的屬性和已刪除的字段之間的區(qū)別。因為這對于布爾值是不可能的(布爾值沒有不合理的值)，所以您要特別警惕刪除(甚至不再使用)布爾類型的字段。

效率和局限性

正如我在較早的概述中[3]所討論的那樣[4]，gRPC服務(wù)的功能之一是它們的消息比基于HTTP的(RESTful)服務(wù)小得多。如果您真的想利用這種效率，請注意位置1到15僅需要一個字節(jié)的額外開銷(即超出存儲值的數(shù)據(jù))，而位置16到2047則需要兩個字節(jié)。將消息格式保持在16位以下似乎是個好主意。

有關(guān)將數(shù)據(jù)打包到盡可能小的空間的選擇類型方面的其他效率提示，請參閱規(guī)范中的標(biāo)量類型說明[5]。

順便說一句，您不能使用以下任何一種作為字段位置編號：負數(shù)，0、19,000到19,999(保留給ProtoBuf使用)或大于536,870,911的數(shù)字。我是否也可以建議，如果您想使用這些數(shù)字，那么您將遇到在本專欄中我無法解決的問題。

真的。別那樣做。

References

[1] Protocol Buffers規(guī)范中: https://developers.google.com/protocol-buffers/docs/proto3#scalar

[2] 規(guī)范: https://developers.google.com/protocol-buffers/docs/proto3

[3] 較早的概述中: https://visualstudiomagazine.com/articles/2019/08/28/grpc-web-services.aspx

[4] 那樣: https://visualstudiomagazine.com/articles/2019/08/28/grpc-web-services.aspx

[5] 標(biāo)量類型說明: https://developers.google.com/protocol-buffers/docs/proto3#scalar