如何在.net core中為grpc服務設計消息文件（proto）

如何在.net core中為grpc服務設計消息

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

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

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

• 您的grpc服務提供的方法
• 這些方法的參數(shù)和返回值的數(shù)據(jù)結構

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

如果您要開始一個新項目，則要使用自2016年以來的proto3語法。但是，您必須在.proto文件的第一行“非空”行上明確指定proto3標準。引用規(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)重復的字段編號（盡管visual studio將發(fā)現(xiàn)任何重復的編號，并在構建應用程序時將其報告在“錯誤列表”中）。如果需要，您也可以跳過職位。此定義僅使用奇數(shù)，例如：

message customerresponse {
int32 custid = 1;
string firstname = 3;
string lastname = 5;
}

在.net core中，消息格式被轉換為類，每個字段都成為與消息同名的類的屬性。命名這些屬性時，.net core還將字段名稱的第一個字符轉換為大寫。因此，例如，我上一個示例中的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é)復制到的數(shù)組和起始位置：

cr.valid.copyto(bytes,0);

數(shù)組和字典

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

message customer {
 int32 id = 1;
 repeated fixed32 transactionamounts = 4;

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

customerresponse cr = new customerresponse
          {
              creditlimit = {10, 15, 100}    
          };

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

cr.creditlimit.add（200）;

您可以使用linq方法（例如first（））或按位置訪問repeatedfield中的項目?？梢哉９ぷ鳎纾?/p>

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字段具有的字段時），客戶端只會發(fā)現(xiàn)服務器未發(fā)送的屬性被設置為其默認值。順便說一句，在服務器的.proto文件中定義的，未在客戶端的.proto文件中定義的字段仍會發(fā)送到客戶端，但是.net不能提供一種方便的方式來訪問它（至少現(xiàn)在還沒有）。

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

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

但是，從.proto文件生成的屬性不可為空，因此，如果未將屬性設置為值，則它將被設置為其默認值。這意味著數(shù)字被設置為0；數(shù)字被設置為0。將string設置為string.empty（長度為零的字符串）；布爾變成虛假的；bytestring屬性默認為bytestring對象，其isempty屬性設置為true；并且repeatedfield和mapfield屬性均默認為其對應的對象，每個對象均不包含任何項目，并且其count屬性設置為0。

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

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

效率和局限性

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

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

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

真的。別那樣做。

以上就是如何在.net core中為grpc服務設計消息文件（proto）的詳細內容，更多關于.net core中為grpc服務設計消息文件的資料請關注碩編程其它相關文章！