當前位置：首頁 > 编程资源 > 编程问答 >内容正文

编程问答

protobuf3 自定义option_Protobuf3 语法指南

發布時間：2023/12/3 编程问答 33 豆豆

生活随笔收集整理的這篇文章主要介紹了 protobuf3 自定义option_Protobuf3 语法指南小編覺得挺不錯的,現在分享給大家,幫大家做個參考.

以前我翻譯了?Protobuf2 語法指南，現在?千念飛羽把protobuf3的語法指南也翻譯了，我也轉載一下，讀者可以有個參考。譯文地址是:?Protobuf3語言指南。

英文原文：

Language Guide (proto3)

中文出處：

Protobuf語言指南

[譯]Protobuf 語法指南

中文出處是proto2的譯文，proto3的英文出現后在原來基礎上增改了，水平有限，還請指正

這個指南描述了如何使用Protocol buffer 語言去描述你的protocol buffer 數據，包括 .proto文件符號和如何從.proto文件生成類。包含了proto2版本的protocol buffer語言：對于老版本的proto3 符號，請見Proto2 Language Guide(以及中文譯本，抄了很多這里的感謝下老版本的翻譯者)

本文是一個參考指南——如果要查看如何使用本文中描述的多個特性的循序漸進的例子，請在教程中查找需要的語言的教程。

定義一個消息類型

先來看一個非常簡單的例子。假設你想定義一個“搜索請求”的消息格式，每一個請求含有一個查詢字符串、你感興趣的查詢結果所在的頁數，以及每一頁多少條查詢結果?？梢圆捎萌缦碌姆绞絹矶x消息類型的.proto文件了：

syntax = "proto3";

message SearchRequest {

string query = 1;

int32 page_number = 2;

int32 result_per_page = 3;

}

文件的第一行指定了你正在使用proto3語法：如果你沒有指定這個，編譯器會使用proto2。這個指定語法行必須是文件的非空非注釋的第一個行。

SearchRequest消息格式有3個字段，在消息中承載的數據分別對應于每一個字段。其中每個字段都有一個名字和一種類型。

指定字段類型

在上面的例子中，所有字段都是標量類型：兩個整型(page_number和result_per_page)，一個string類型(query)。當然，你也可以為字段指定其他的合成類型，包括枚舉(enumerations)或其他消息類型。

分配標識號

正如你所見，在消息定義中，每個字段都有唯一的一個數字標識符。這些標識符是用來在消息的二進制格式中識別各個字段的，一旦開始使用就不能夠再改變。注：[1,15]之內的標識號在編碼的時候會占用一個字節。[16,2047]之內的標識號則占用2個字節。所以應該為那些頻繁出現的消息元素保留 [1,15]之內的標識號。切記：要為將來有可能添加的、頻繁出現的標識號預留一些標識號。

最小的標識號可以從1開始，最大到2^29 - 1, or 536,870,911。不可以使用其中的[19000－19999]( (從FieldDescriptor::kFirstReservedNumber 到 FieldDescriptor::kLastReservedNumber))的標識號， Protobuf協議實現中對這些進行了預留。如果非要在.proto文件中使用這些預留標識號，編譯時就會報警。同樣你也不能使用早期保留的標識號。

指定字段規則

所指定的消息字段修飾符必須是如下之一：

singular：一個格式良好的消息應該有0個或者1個這種字段(但是不能超過1個)。

repeated：在一個格式良好的消息中，這種字段可以重復任意多次(包括0次)。重復的值的順序會被保留。

在proto3中，repeated的標量域默認情況蝦使用packed。

添加更多消息類型

在一個.proto文件中可以定義多個消息類型。在定義多個相關的消息的時候，這一點特別有用——例如，如果想定義與SearchResponse消息類型對應的回復消息格式的話，你可以將它添加到相同的.proto文件中，如：

message SearchRequest {

string query = 1;

int32 page_number = 2;

int32 result_per_page = 3;

}

message SearchResponse {

...

}

添加注釋

向.proto文件添加注釋，可以使用C/C++/Java風格的雙斜杠(//) 語法格式，如：

message SearchRequest {

string query = 1;

int32 page_number = 2; // Which page number do we want?

int32 result_per_page = 3; // Number of results to return per page.

}

保留標識符(Reserved)

如果你通過刪除或者注釋所有域，以后的用戶在更新這個類型的時候可能重用這些標識號。如果你使用舊版本加載相同的.proto文件會導致嚴重的問題，包括數據損壞、隱私錯誤等等。現在有一種確保不會發生這種情況的方法就是為字段tag(reserved name可能會JSON序列化的問題)指定reserved標識符，protocol buffer的編譯器會警告未來嘗試使用這些域標識符的用戶。

message Foo {

reserved 2, 15, 9 to 11;

reserved "foo", "bar";

}

注：不要在同一行reserved聲明中同時聲明域名字和tag number。

從.proto文件生成了什么？

當用protocol buffer編譯器來運行.proto文件時，編譯器將生成所選擇語言的代碼，這些代碼可以操作在.proto文件中定義的消息類型，包括獲取、設置字段值，將消息序列化到一個輸出流中，以及從一個輸入流中解析消息。

對C++來說，編譯器會為每個.proto文件生成一個.h文件和一個.cc文件，.proto文件中的每一個消息有一個對應的類。

對Java來說，編譯器為每一個消息類型生成了一個.java文件，以及一個特殊的Builder類(該類是用來創建消息類接口的)。

對Python來說，有點不太一樣——Python編譯器為.proto文件中的每個消息類型生成一個含有靜態描述符的模塊，，該模塊與一個元類(metaclass)在運行時(runtime)被用來創建所需的Python數據訪問類。

對go來說，編譯器會位每個消息類型生成了一個.pd.go文件。

對于Ruby來說，編譯器會為每個消息類型生成了一個.rb文件。

javaNano來說，編譯器輸出類似域java但是沒有Builder類

對于Objective-C來說，編譯器會為每個消息類型生成了一個pbobjc.h文件和pbobjcm文件，.proto文件中的每一個消息有一個對應的類。

對于C#來說，編譯器會為每個消息類型生成了一個.cs文件，.proto文件中的每一個消息有一個對應的類。

你可以從如下的文檔鏈接中獲取每種語言更多API(proto3版本的內容很快就公布)。API Reference

標量數值類型

一個標量消息字段可以含有一個如下的類型——該表格展示了定義于.proto文件中的類型，以及與之對應的、在自動生成的訪問類中定義的類型：

.proto TypeNotesC++ TypeJava TypePython Type[2]Go TypeRuby TypeC# TypePHP Type

double

float

float64

Float

double

float

float32

Float

float

int32

使用變長編碼，對于負值的效率很低，如果你的域有可能有負值，請使用sint64替代

int32

int

int32

Fixnum 或者 Bignum(根據需要)

int

integer

uint32

使用變長編碼

uint32

int

int/long

uint32

Fixnum 或者 Bignum(根據需要)

uint

integer

uint64

使用變長編碼

uint64

long

int/long

uint64

Bignum

ulong

integer/string

sint32

使用變長編碼，這些編碼在負值時比int32高效的多

int32

int

int32

Fixnum 或者 Bignum(根據需要)

int

integer

sint64

使用變長編碼，有符號的整型值。編碼時比通常的int64高效。

int64

long

int/long

int64

Bignum

long

integer/string

fixed32

總是4個字節，如果數值總是比總是比228大的話，這個類型會比uint32高效。

uint32

int

uint32

Fixnum 或者 Bignum(根據需要)

uint

integer

fixed64

總是8個字節，如果數值總是比總是比256大的話，這個類型會比uint64高效。

uint64

long

int/long

uint64

Bignum

ulong

integer/string

sfixed32

總是4個字節

int32

int

int32

Fixnum 或者 Bignum(根據需要)

int

integer

sfixed64

總是8個字節

int64

long

int/long

int64

Bignum

long

integer/string

bool

boolean

bool

TrueClass/FalseClass

bool

boolean

string

一個字符串必須是UTF-8編碼或者7-bit ASCII編碼的文本。

string

String

str/unicode

string

String (UTF-8)

string

bytes

可能包含任意順序的字節數據。

string

ByteString

str

[]byte

String (ASCII-8BIT)

ByteString

string

你可以在文章Protocol Buffer 編碼中，找到更多“序列化消息時各種類型如何編碼”的信息。

在java中，無符號32位和64位整型被表示成他們的整型對應形式，最高位被儲存在標志位中。

對于所有的情況，設定值會執行類型檢查以確保此值是有效。

64位或者無符號32位整型在解碼時被表示成為ilong，但是在設置時可以使用int型值設定，在所有的情況下，值必須符合其設置其類型的要求。

python中string被表示成在解碼時表示成unicode。但是一個ASCIIstring可以被表示成str類型。

Integer在64位的機器上使用，string在32位機器上使用

默認值

當一個消息被解析的時候，如果被編碼的信息不包含一個特定的singular元素，被解析的對象鎖對應的域被設置位一個默認值，對于不同類型指定如下：

對于string，默認是一個空string

對于bytes，默認是一個空的bytes

對于bool，默認是false

對于數值類型，默認是0

對于枚舉，默認是第一個定義的枚舉值，必須為0;

對于消息類型(message)，域沒有被設置，確切的消息是根據語言確定的，詳見generated code guide

對于可重復域的默認值是空(通常情況下是對應語言中空列表)。

注：對于標量消息域，一旦消息被解析，就無法判斷域釋放被設置為默認值(例如，例如boolean值是否被設置為false)還是根本沒有被設置。你應該在定義你的消息類型時非常注意。例如，比如你不應該定義boolean的默認值false作為任何行為的觸發方式。也應該注意如果一個標量消息域被設置為標志位，這個值不應該被序列化傳輸。

枚舉

當需要定義一個消息類型的時候，可能想為一個字段指定某“預定義值序列”中的一個值。例如，假設要為每一個SearchRequest消息添加一個 corpus字段，而corpus的值可能是UNIVERSAL，WEB，IMAGES，LOCAL，NEWS，PRODUCTS或VIDEO中的一個。其實可以很容易地實現這一點：通過向消息定義中添加一個枚舉(enum)并且為每個可能的值定義一個常量就可以了。

在下面的例子中，在消息格式中添加了一個叫做Corpus的枚舉類型——它含有所有可能的值 ——以及一個類型為Corpus的字段：

message SearchRequest {

string query = 1;

int32 page_number = 2;

int32 result_per_page = 3;

enum Corpus {

UNIVERSAL = 0;

WEB = 1;

IMAGES = 2;

LOCAL = 3;

NEWS = 4;

PRODUCTS = 5;

VIDEO = 6;

}

Corpus corpus = 4;

}

如你所見，Corpus枚舉的第一個常量映射為0：每個枚舉類型必須將其第一個類型映射為0，這是因為：

必須有有一個0值，我們可以用這個0值作為默認值。

這個零值必須為第一個元素，為了兼容proto2語義，枚舉類的第一個值總是默認值。

你可以通過將不同的枚舉常量指定位相同的值。如果這樣做你需要將allow_alias設定位true，否則編譯器會在別名的地方產生一個錯誤信息。

enum EnumAllowingAlias {

option allow_alias = true;

UNKNOWN = 0;

STARTED = 1;

RUNNING = 1;

}

enum EnumNotAllowingAlias {

UNKNOWN = 0;

STARTED = 1;

// RUNNING = 1; // Uncommenting this line will cause a compile error inside Google and a warning message outside.

}

枚舉常量必須在32位整型值的范圍內。因為enum值是使用可變編碼方式的，對負數不夠高效，因此不推薦在enum中使用負數。如上例所示，可以在一個消息定義的內部或外部定義枚舉——這些枚舉可以在.proto文件中的任何消息定義里重用。當然也可以在一個消息中聲明一個枚舉類型，而在另一個不同的消息中使用它——采用MessageType.EnumType的語法格式。

當對一個使用了枚舉的.proto文件運行protocol buffer編譯器的時候，生成的代碼中將有一個對應的enum(對Java或C++來說)，或者一個特殊的EnumDescriptor類(對 Python來說)，它被用來在運行時生成的類中創建一系列的整型值符號常量(symbolic constants)。

在反序列化的過程中，無法識別的枚舉值會被保存在消息中，雖然這種表示方式需要依據所使用語言而定。在那些支持開放枚舉類型超出指定范圍之外的語言中(例如C++和Go)，為識別的值會被表示成所支持的整型。在使用封閉枚舉類型的語言中(Java)，使用枚舉中的一個類型來表示未識別的值，并且可以使用所支持整型來訪問。在其他情況下，如果解析的消息被序列號，未識別的值將保持原樣。

關于如何在你的應用程序的消息中使用枚舉的更多信息，請查看所選擇的語言generated code guide。

使用其他消息類型

你可以將其他消息類型用作字段類型。例如，假設在每一個SearchResponse消息中包含Result消息，此時可以在相同的.proto文件中定義一個Result消息類型，然后在SearchResponse消息中指定一個Result類型的字段，如：

message SearchResponse {

repeated Result results = 1;

}

message Result {

string url = 1;

string title = 2;

repeated string snippets = 3;

}

導入定義

在上面的例子中，Result消息類型與SearchResponse是定義在同一文件中的。如果想要使用的消息類型已經在其他.proto文件中已經定義過了呢？

你可以通過導入(importing)其他.proto文件中的定義來使用它們。要導入其他.proto文件的定義，你需要在你的文件中添加一個導入聲明，如：

import "myproject/other_protos.proto";

默認情況下你只能使用直接導入的.proto文件中的定義. 然而，有時候你需要移動一個.proto文件到一個新的位置，可以不直接移動.proto文件，只需放入一個偽 .proto 文件在老的位置，然后使用import public轉向新的位置。import public 依賴性會通過任意導入包含import public聲明的proto文件傳遞。例如：

// 這是新的proto

// All definitions are moved here

// 這是久的proto

// 這是所有客戶端正在導入的包

import public "new.proto";

import "other.proto";

// 客戶端proto

import "old.proto";

// 現在你可以使用新舊兩種包的proto定義了。

通過在編譯器命令行參數中使用-I/--proto_pathprotocal 編譯器會在指定目錄搜索要導入的文件。如果沒有給出標志，編譯器會搜索編譯命令被調用的目錄。通常你只要指定proto_path標志為你的工程根目錄就好。并且指定好導入的正確名稱就好。

使用proto2消息類型

在你的proto3消息中導入proto2的消息類型也是可以的，反之亦然，然后proto2枚舉不可以直接在proto3的標識符中使用(如果僅僅在proto2消息中使用是可以的)。

嵌套類型

你可以在其他消息類型中定義、使用消息類型，在下面的例子中，Result消息就定義在SearchResponse消息內，如：

message SearchResponse {

message Result {

string url = 1;

string title = 2;

repeated string snippets = 3;

}

repeated Result results = 1;

}

如果你想在它的父消息類型的外部重用這個消息類型，你需要以Parent.Type的形式使用它，如：

message SomeOtherMessage {

SearchResponse.Result result = 1;

}

當然，你也可以將消息嵌套任意多層，如：

message Outer { // Level 0

message MiddleAA { // Level 1

message Inner { // Level 2

int64 ival = 1;

bool booly = 2;

}

message MiddleBB { // Level 1

message Inner { // Level 2

int32 ival = 1;

bool booly = 2;

}

更新一個消息類型

如果一個已有的消息格式已無法滿足新的需求——如，要在消息中添加一個額外的字段——但是同時舊版本寫的代碼仍然可用。不用擔心！更新消息而不破壞已有代碼是非常簡單的。在更新時只要記住以下的規則即可。

不要更改任何已有的字段的數值標識。

如果你增加新的字段，使用舊格式的字段仍然可以被你新產生的代碼所解析。你應該記住這些元素的默認值這樣你的新代碼就可以以適當的方式和舊代碼產生的數據交互。相似的，通過新代碼產生的消息也可以被舊代碼解析：只不過新的字段會被忽視掉。注意，未被識別的字段會在反序列化的過程中丟棄掉，所以如果消息再被傳遞給新的代碼，新的字段依然是不可用的(這和proto2中的行為是不同的，在proto2中未定義的域依然會隨著消息被序列化)

非required的字段可以移除——只要它們的標識號在新的消息類型中不再使用(更好的做法可能是重命名那個字段，例如在字段前添加“OBSOLETE_”前綴，那樣的話，使用的.proto文件的用戶將來就不會無意中重新使用了那些不該使用的標識號)。

int32, uint32, int64, uint64,和bool是全部兼容的，這意味著可以將這些類型中的一個轉換為另外一個，而不會破壞向前、向后的兼容性。如果解析出來的數字與對應的類型不相符，那么結果就像在C++中對它進行了強制類型轉換一樣(例如，如果把一個64位數字當作int32來讀取，那么它就會被截斷為32位的數字)。

sint32和sint64是互相兼容的，但是它們與其他整數類型不兼容。

string和bytes是兼容的——只要bytes是有效的UTF-8編碼。

嵌套消息與bytes是兼容的——只要bytes包含該消息的一個編碼過的版本。

fixed32與sfixed32是兼容的，fixed64與sfixed64是兼容的。

枚舉類型與int32，uint32，int64和uint64相兼容(注意如果值不相兼容則會被截斷)，然而在客戶端反序列化之后他們可能會有不同的處理方式，例如，未識別的proto3枚舉類型會被保留在消息中，但是他的表示方式會依照語言而定。int類型的字段總會保留他們的

Any

Any類型消息允許你在沒有指定他們的.proto定義的情況下使用消息作為一個嵌套類型。一個Any類型包括一個可以被序列化bytes類型的任意消息，以及一個URL作為一個全局標識符和解析消息類型。為了使用Any類型，你需要導入import google/protobuf/any.proto。

import "google/protobuf/any.proto";

message ErrorStatus {

string message =1;

repeated google.protobuf.Any details =2;

}

對于給定的消息類型的默認類型URL是type.googleapis.com/packagename.messagename。

不同語言的實現會支持動態庫以線程安全的方式去幫助封裝或者解封裝Any值。例如在java中，Any類型會有特殊的pack()和unpack()訪問器，在C++中會有PackFrom()和UnpackTo()方法。

// Storing an arbitrary message type in Any.

NetworkErrorDetails details = ...;

ErrorStatus status;

status.add_details()->PackFrom(details);

// Reading an arbitrary message from Any.

ErrorStatus status = ...;

for (const Any& detail : status.details()) {

if (detail.Is()) {

NetworkErrorDetails network_error;

detail.UnpackTo(&network_error);

... processing network_error ...

}

目前，用于Any類型的動態庫仍在開發之中

如果你已經很熟悉proto2語法，使用Any替換擴展。

Oneof

如果你的消息中有很多可選字段，并且同時至多一個字段會被設置，你可以加強這個行為，使用oneof特性節省內存.

Oneof字段就像可選字段，除了它們會共享內存，至多一個字段會被設置。設置其中一個字段會清除其它字段。你可以使用case()或者WhichOneof()?方法檢查哪個oneof字段被設置，看你使用什么語言了.

使用Oneof

為了在.proto定義Oneof字段，你需要在名字前面加上oneof關鍵字, 比如下面例子的test_oneof:

message SampleMessage {

oneof test_oneof {

string name = 4;

SubMessage sub_message = 9;

}

然后你可以增加oneof字段到 oneof 定義中. 你可以增加任意類型的字段, 但是不能使用repeated 關鍵字.

在產生的代碼中, oneof字段擁有同樣的 getters 和setters，就像正常的可選字段一樣. 也有一個特殊的方法來檢查到底那個字段被設置. 你可以在相應的語言API指南中找到oneof API介紹.

Oneof 特性

設置oneof會自動清楚其它oneof字段的值. 所以設置多次后，只有最后一次設置的字段有值.

SampleMessage message;

message.set_name("name");

CHECK(message.has_name());

message.mutable_sub_message(); // Will clear name field.

CHECK(!message.has_name());

如果解析器遇到同一個oneof中有多個成員，只有最會一個會被解析成消息。

oneof不支持repeated.

反射API對oneof 字段有效.

如果使用C++,需確保代碼不會導致內存泄漏. 下面的代碼會崩潰，因為sub_message 已經通過set_name()刪除了

SampleMessage message;

SubMessage* sub_message = message.mutable_sub_message();

message.set_name("name"); // Will delete sub_message

sub_message->set_... // Crashes here

在C++中，如果你使用Swap()兩個oneof消息，每個消息，兩個消息將擁有對方的值，例如在下面的例子中，msg1會擁有sub_message并且msg2會有name。

SampleMessage msg1;

msg1.set_name("name");

SampleMessage msg2;

msg2.mutable_sub_message();

msg1.swap(&msg2);

CHECK(msg1.has_sub_message());

CHECK(msg2.has_name());

向后兼容性問題

當增加或者刪除oneof字段時一定要小心. 如果檢查oneof的值返回None/NOT_SET, 它意味著oneof字段沒有被賦值或者在一個不同的版本中賦值了。你不會知道是哪種情況，因為沒有辦法判斷如果未識別的字段是一個oneof字段。

Tag 重用問題：

將字段移入或移除oneof：在消息被序列號或者解析后，你也許會失去一些信息(有些字段也許會被清除)

刪除一個字段或者加入一個字段：在消息被序列號或者解析后，這也許會清除你現在設置的oneof字段

分離或者融合oneof：行為與移動常規字段相似。

Map

如果你希望創建一個關聯映射，protocol buffer提供了一種快捷的語法：

map map_field = N;

其中key_type可以是任意Integer或者string類型(所以，除了floating和bytes的任意標量類型都是可以的)value_type可以是任意類型。

例如，如果你希望創建一個project的映射，每個Projecct使用一個string作為key，你可以像下面這樣定義：

map projects = 3;

Map的字段可以是repeated。

序列化后的順序和map迭代器的順序是不確定的，所以你不要期望以固定順序處理Map

當為.proto文件產生生成文本格式的時候，map會按照key 的順序排序，數值化的key會按照數值排序。

從序列化中解析或者融合時，如果有重復的key則后一個key不會被使用，當從文本格式中解析map時，如果存在重復的key。

生成map的API現在對于所有proto3支持的語言都可用了，你可以從API指南找到更多信息。

向后兼容性問題

map語法序列化后等同于如下內容，因此即使是不支持map語法的protocol buffer實現也是可以處理你的數據的：

message MapFieldEntry {

key_type key = 1;

value_type value = 2;

}

repeated MapFieldEntry map_field = N;

Package

當然可以為.proto文件新增一個可選的package聲明符，用來防止不同的消息類型有命名沖突。如：

package foo.bar;

message Open { ... }

在其他的消息格式定義中可以使用包名+消息名的方式來定義域的類型，如：

message Foo {

...

required foo.bar.Open open =1;

...

}

包的聲明符會根據使用語言的不同影響生成的代碼。

對于C++，產生的類會被包裝在C++的命名空間中，如上例中的Open會被封裝在 foo::bar空間中； - 對于Java，包聲明符會變為java的一個包，除非在.proto文件中提供了一個明確有java_package；

對于 Python，這個包聲明符是被忽略的，因為Python模塊是按照其在文件系統中的位置進行組織的。

對于Go，包可以被用做Go包名稱，除非你顯式的提供一個option go_package在你的.proto文件中。

對于Ruby，生成的類可以被包裝在內置的Ruby名稱空間中，轉換成Ruby所需的大小寫樣式 (首字母大寫；如果第一個符號不是一個字母，則使用PB_前綴)，例如Open會在Foo::Bar名稱空間中。

對于javaNano包會使用Java包，除非你在你的文件中顯式的提供一個option java_package。

對于C#包可以轉換為PascalCase后作為名稱空間，除非你在你的文件中顯式的提供一個option csharp_namespace，例如，Open會在Foo.Bar名稱空間中

包及名稱的解析

Protocol buffer語言中類型名稱的解析與C++是一致的：首先從最內部開始查找，依次向外進行，每個包會被看作是其父類包的內部類。當然對于 (foo.bar.Baz)這樣以“.”分隔的意味著是從最外圍開始的。

ProtocolBuffer編譯器會解析.proto文件中定義的所有類型名。對于不同語言的代碼生成器會知道如何來指向每個具體的類型，即使它們使用了不同的規則。

定義服務(Service)

如果想要將消息類型用在RPC(遠程方法調用)系統中，可以在.proto文件中定義一個RPC服務接口，protocol buffer編譯器將會根據所選擇的不同語言生成服務接口代碼及存根。如，想要定義一個RPC服務并具有一個方法，該方法能夠接收 SearchRequest并返回一個SearchResponse，此時可以在.proto文件中進行如下定義：

service SearchService {

rpc Search (SearchRequest) returns (SearchResponse);

}

最直觀的使用protocol buffer的RPC系統是gRPC,一個由谷歌開發的語言和平臺中的開源的PRC系統，gRPC在使用protocl buffer時非常有效，如果使用特殊的protocol buffer插件可以直接為您從.proto文件中產生相關的RPC代碼。

如果你不想使用gRPC，也可以使用protocol buffer用于自己的RPC實現，你可以從proto2語言指南中找到更多信息

還有一些第三方開發的PRC實現使用Protocol Buffer。參考第三方插件wiki查看這些實現的列表。

JSON 映射

Proto3 支持JSON的編碼規范，使他更容易在不同系統之間共享數據，在下表中逐個描述類型。

如果JSON編碼的數據丟失或者其本身就是null，這個數據會在解析成protocol buffer的時候被表示成默認值。如果一個字段在protocol buffer中表示為默認值，體會在轉化成JSON的時候編碼的時候忽略掉以節省空間。具體實現可以提供在JSON編碼中可選的默認值。

proto3JSONJSON示例注意

message

object

{“fBar”: v, “g”: null, …}

產生JSON對象，消息字段名可以被映射成lowerCamelCase形式，并且成為JSON對象鍵，null被接受并成為對應字段的默認值

enum

string

“FOO_BAR”

枚舉值的名字在proto文件中被指定

map

object

{“k”: v, …}

所有的鍵都被轉換成string

repeated V

array

[v, …]

null被視為空列表

bool

true, false

string

“Hello World!”

bytes

base64 string

“YWJjMTIzIT8kKiYoKSctPUB+”

int32, fixed32, uint32

number

1, -10, 0

JSON值會是一個十進制數，數值型或者string類型都會接受

int64, fixed64, uint64

string

“1”, “-10”

JSON值會是一個十進制數，數值型或者string類型都會接受

float, double

number

1.1, -10.0, 0, “NaN”, “Infinity”

JSON值會是一個數字或者一個指定的字符串如”NaN”,”infinity”或者”-Infinity”，數值型或者字符串都是可接受的，指數符號也可以接受

Any

object

{“@type”: “url”, “f”: v, … }

如果一個Any保留一個特上述的JSON映射，則它會轉換成一個如下形式：{"@type": xxx, "value": yyy}否則，該值會被轉換成一個JSON對象，@type字段會被插入所指定的確定的值

Timestamp

string

“1972-01-01T10:00:20.021Z”

使用RFC 339，其中生成的輸出將始終是Z-歸一化啊的，并且使用0，3，6或者9位小數

Duration

string

“1.000340012s”, “1s”

生成的輸出總是0，3，6或者9位小數，具體依賴于所需要的精度，接受所有可以轉換為納秒級的精度

Struct

object

{ … }

任意的JSON對象，見struct.proto

Wrapper types

various types

2, “2”, “foo”, true, “true”, null, 0, …

包裝器在JSON中的表示方式類似于基本類型，但是允許nulll，并且在轉換的過程中保留null

FieldMask

string

“f.fooBar,h”

見fieldmask.proto

ListValue

array

[foo, bar, …]

Value

value

任意JSON值

NullValue

null

JSON null

選項

定義.proto文件時能夠標注一系列的option。Option并不改變整個文件聲明的含義，但卻能夠影響特定環境下處理方式。完整的可用選項可以在google/protobuf/descriptor.proto找到。

一些選項是文件級別的，意味著它可以作用于最外范圍，不包含在任何消息內部、enum或服務定義中。一些選項是消息級別的，意味著它可以用在消息定義的內部。當然有些選項可以作用在域、enum類型、enum值、服務類型及服務方法中。到目前為止，并沒有一種有效的選項能作用于所有的類型。

如下就是一些常用的選項：

java_package (文件選項) :這個選項表明生成java類所在的包。如果在.proto文件中沒有明確的聲明java_package，就采用默認的包名。當然了，默認方式產生的 java包名并不是最好的方式，按照應用名稱倒序方式進行排序的。如果不需要產生java代碼，則該選項將不起任何作用。如：

option java_package = "com.example.foo";

java_outer_classname (文件選項): 該選項表明想要生成Java類的名稱。如果在.proto文件中沒有明確的java_outer_classname定義，生成的class名稱將會根據.proto文件的名稱采用駝峰式的命名方式進行生成。如(foo_bar.proto生成的java類名為FooBar.java),如果不生成java代碼，則該選項不起任何作用。如：

option java_outer_classname = "Ponycopter";

optimize_for(文件選項): 可以被設置為 SPEED, CODE_SIZE,或者LITE_RUNTIME。這些值將通過如下的方式影響C++及java代碼的生成：

SPEED (default): protocol buffer編譯器將通過在消息類型上執行序列化、語法分析及其他通用的操作。這種代碼是最優的。

CODE_SIZE: protocol buffer編譯器將會產生最少量的類，通過共享或基于反射的代碼來實現序列化、語法分析及各種其它操作。采用該方式產生的代碼將比SPEED要少得多，但是操作要相對慢些。當然實現的類及其對外的API與SPEED模式都是一樣的。這種方式經常用在一些包含大量的.proto文件而且并不盲目追求速度的應用中。

LITE_RUNTIME: protocol buffer編譯器依賴于運行時核心類庫來生成代碼(即采用libprotobuf-lite 替代libprotobuf)。這種核心類庫由于忽略了一些描述符及反射，要比全類庫小得多。這種模式經常在移動手機平臺應用多一些。編譯器采用該模式產生的方法實現與SPEED模式不相上下，產生的類通過實現 MessageLite接口，但它僅僅是Messager接口的一個子集。

option optimize_for = CODE_SIZE;

cc_enable_arenas(文件選項):對于C++產生的代碼啟用arena allocation

objc_class_prefix(文件選項):設置Objective-C類的前綴，添加到所有Objective-C從此.proto文件產生的類和枚舉類型。沒有默認值，所使用的前綴應該是蘋果推薦的3-5個大寫字符，注意2個字節的前綴是蘋果所保留的。

deprecated(字段選項):如果設置為true則表示該字段已經被廢棄，并且不應該在新的代碼中使用。在大多數語言中沒有實際的意義。在java中，這回變成@Deprecated注釋，在未來，其他語言的代碼生成器也許會在字標識符中產生廢棄注釋，廢棄注釋會在編譯器嘗試使用該字段時發出警告。如果字段沒有被使用你也不希望有新用戶使用它，嘗試使用保留語句替換字段聲明。

int32 old_field = 6 [deprecated=true];

自定義選項

ProtocolBuffers允許自定義并使用選項。該功能應該屬于一個高級特性，對于大部分人是用不到的。如果你的確希望創建自己的選項，請參看 Proto2 Language Guide。注意創建自定義選項使用了拓展，拓展只在proto3中可用。

生成訪問類

可以通過定義好的.proto文件來生成Java,Python,C++, Ruby, JavaNano, Objective-C,或者C# 代碼，需要基于.proto文件運行protocol buffer編譯器protoc。如果你沒有安裝編譯器，下載安裝包并遵照README安裝。對于Go,你還需要安裝一個特殊的代碼生成器插件。你可以通過GitHub上的protobuf庫找到安裝過程

通過如下方式調用protocol編譯器：

protoc --proto_path=IMPORT_PATH --cpp_out=DST_DIR --java_out=DST_DIR --python_out=DST_DIR --go_out=DST_DIR --ruby_out=DST_DIR --javanano_out=DST_DIR --objc_out=DST_DIR --csharp_out=DST_DIR path/to/file.proto

IMPORT_PATH聲明了一個.proto文件所在的解析import具體目錄。如果忽略該值，則使用當前目錄。如果有多個目錄則可以多次調用--proto_path，它們將會順序的被訪問并執行導入。-I=IMPORT_PATH是--proto_path的簡化形式。

當然也可以提供一個或多個輸出路徑：

--cpp_out 在目標目錄DST_DIR中產生C++代碼，可以在C++代碼生成參考中查看更多。

--java_out 在目標目錄DST_DIR中產生Java代碼，可以在?Java代碼生成參考中查看更多。

--python_out 在目標目錄 DST_DIR 中產生Python代碼，可以在Python代碼生成參考中查看更多。

--go_out 在目標目錄 DST_DIR 中產生Go代碼，可以在GO代碼生成參考中查看更多。

--ruby_out在目標目錄 DST_DIR 中產生Ruby代碼，參考正在制作中。

--javanano_out在目標目錄DST_DIR中生成JavaNano，JavaNano代碼生成器有一系列的選項用于定制自定義生成器的輸出：你可以通過生成器的README查找更多信息，JavaNano參考正在制作中。

--objc_out在目標目錄DST_DIR中產生Object代碼，可以在Objective-C代碼生成參考中查看更多。

--csharp_out在目標目錄DST_DIR中產生Object代碼，可以在C#代碼生成參考中查看更多。

--php_out在目標目錄DST_DIR中產生Object代碼，可以在PHP代碼生成參考中查看更多。

作為一個方便的拓展，如果DST_DIR以.zip或者.jar結尾，編譯器會將輸出寫到一個ZIP格式文件或者符合JAR標準的.jar文件中。注意如果輸出已經存在則會被覆蓋，編譯器還沒有智能到可以追加文件。

你必須提議一個或多個.proto文件作為輸入，多個.proto文件可以只指定一次。雖然文件路徑是相對于當前目錄的，每個文件必須位于其IMPORT_PATH下，以便每個文件可以確定其規范的名稱。

總結

以上是生活随笔為你收集整理的protobuf3 自定义option_Protobuf3 语法指南的全部內容，希望文章能夠幫你解決所遇到的問題。

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