如何在.NET Core中為gRPC服務設計消息文件（Proto）

Posted on 2021-05-07 by WalkonNet

如何在.NET Core中為gRPC服務設計消息

使用協議緩沖區規范定義gRPC服務非常容易，但從需求轉換為.NET Core，然後管理服務的演變時，需要註意幾件事。

創建gRPC服務的核心是.proto文件，該文件以與語言無關的格式描述瞭該服務。使用.proto文件，Visual Studio可以為您的服務生成基類（您隻需編寫特定於業務的代碼），或者可以生成用於可靠訪問服務的客戶端類。

.proto文件必須符合Google的協議緩沖區規范（通常稱為ProtoBuf）。原始文件的內容使您可以指定服務的接口。服務接口由兩部分組成：

您的gRPC服務提供的方法
這些方法的參數和返回值的數據結構

您可以使用Protocol Buffers規范中[1]定義的標量類型來構建這些數據結構（在ProtoBuf中稱為“消息”）。可用的類型包括佈爾值，字符串，字節數組和各種數字類型（浮點型，整數型和長型）。沒有日期或固定的十進制類型。在接下來的專欄中，我將向您展示如何添加時間戳類型。對於小數，您可以使用float …並伴隨著float帶來的精度損失。

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

syntax = "proto3";

消息和C＃類

使用proto3規范，用於客戶信息的消息格式可能如下所示：

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

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

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

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

在此過程中，還得刪除字段名稱中的所有下劃線，並且將以下字母大寫（即，Last_name字段名稱變為LastName屬性）。

該過程還涉及將.NET類型映射到ProtoBuf類型（例如，ProtoBuf int32變為.NET int，ProtoBuf的int64變為long，fixed32變為uint），這需要向.NET Core添加一些新類。例如，ProtoBuf支持字節數組，其類型為字節。名為ByteString的新.NET數據類型支持該字段類型。要加載ByteString，請使用ByteString類的靜態CopyFrom方法，並傳遞一個字節數組，如下所示：

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

要從ByteString檢索字節數組，請使用對象的CopyTo方法，並傳遞要將字節復制到的數組和起始位置：

cr.Valid.CopyTo(bytes,0);

數組和字典

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

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

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

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預覽版中，編輯器不會像其他類型一樣突出顯示map對象（盡管編譯得很好）。

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

管理變更

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

同樣，在相反的情況下（當服務器.proto文件沒有客戶端的.proto字段具有的字段時），客戶端隻會發現服務器未發送的屬性被設置為其默認值。順便說一句，在服務器的.proto文件中定義的，未在客戶端的.proto文件中定義的字段仍會發送到客戶端，但是.NET不能提供一種方便的方式來訪問它（至少現在還沒有）。

確實，隨著服務的發展和修改其.proto文件，您僅應遵守兩個規則：

不要更改現有字段的位置編號
不要回收職位編號（即不要用新的字段3替換過時的字段3）

但是，從.proto文件生成的屬性不可為空，因此，如果未將屬性設置為值，則它將被設置為其默認值。這意味著數字被設置為0；數字被設置為0。將string設置為string.Empty（長度為零的字符串）；佈爾變成虛假的；ByteString屬性默認為ByteString對象，其IsEmpty屬性設置為true；並且RepeatedField和MapField屬性均默認為其對應的對象，每個對象均不包含任何項目，並且其Count屬性設置為0。

由於這種行為，存在從服務的.proto文件中刪除字段並且不更新所有客戶端（或者隻是在服務器上生成響應時未在對象上設置屬性）的危險。危險是客戶端無法區分未使用的字段和已設置為其默認值的屬性之間的區別。如果將我的客戶的有效屬性設置為false，則客戶端將無法確定客戶是否無效或服務器是否不再生成該字段。

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

效率和局限性

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

有關將數據打包到盡可能小的空間的選擇類型方面的其他效率提示，請參閱規范中的標量類型說明[5]。

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

真的。別那樣做。

以上就是如何在.NET Core中為gRPC服務設計消息文件（Proto）的詳細內容，更多關於.NET Core中為gRPC服務設計消息文件的資料請關註WalkonNet其它相關文章！

如何在.NET Core中為gRPC服務設計消息文件（Proto）