Protocol Buffers 第 3 版語言規格

Protocol Buffers (proto3) 第 3 版語言的語言規格參考。

|   alternation
()  grouping
[]  option (zero or one time)
{}  repetition (any number of times)

如需更多關於使用 proto3 的資訊，請參閱語言指南。

詞法元素

字母和數字

letter = "A" ... "Z" | "a" ... "z"
decimalDigit = "0" ... "9"
octalDigit   = "0" ... "7"
hexDigit     = "0" ... "9" | "A" ... "F" | "a" ... "f"

識別字

ident = letter { letter | decimalDigit | "_" }
fullIdent = ident { "." ident }
messageName = ident
enumName = ident
fieldName = ident
oneofName = ident
mapName = ident
serviceName = ident
rpcName = ident
messageType = [ "." ] { ident "." } messageName
enumType = [ "." ] { ident "." } enumName

整數常值

intLit     = decimalLit | octalLit | hexLit
decimalLit = [-] ( "1" ... "9" ) { decimalDigit }
octalLit   = [-] "0" { octalDigit }
hexLit     = [-] "0" ( "x" | "X" ) hexDigit { hexDigit }

浮點數常值

floatLit = [-] ( decimals "." [ decimals ] [ exponent ] | decimals exponent | "."decimals [ exponent ] ) | "inf" | "nan"
decimals  = [-] decimalDigit { decimalDigit }
exponent  = ( "e" | "E" ) [ "+" | "-" ] decimals

布林值

boolLit = "true" | "false"

字串常值

strLit = strLitSingle { strLitSingle }
strLitSingle = ( "'" { charValue } "'" ) |  ( '"' { charValue } '"' )
charValue = hexEscape | octEscape | charEscape | unicodeEscape | unicodeLongEscape | /[^\0\n\\]/
hexEscape = '\' ( "x" | "X" ) hexDigit [ hexDigit ]
octEscape = '\' octalDigit [ octalDigit [ octalDigit ] ]
charEscape = '\' ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | '\' | "'" | '"' )
unicodeEscape = '\' "u" hexDigit hexDigit hexDigit hexDigit
unicodeLongEscape = '\' "U" ( "000" hexDigit hexDigit hexDigit hexDigit hexDigit |
                              "0010" hexDigit hexDigit hexDigit hexDigit

空語句

emptyStatement = ";"

常數

constant = fullIdent | ( [ "-" | "+" ] intLit ) | ( [ "-" | "+" ] floatLit ) |
                strLit | boolLit | MessageValue

MessageValue 定義於文字格式語言規格中。

語法

syntax 語句用於定義 protobuf 版本。

syntax = "syntax" "=" ("'" "proto3" "'" | '"' "proto3" '"') ";"

範例

syntax = "proto3";

import 語句

import 語句用於匯入另一個 .proto 檔案的定義。

import = "import" [ "weak" | "public" ] strLit ";"

範例

import public "other.proto";

套件

package 指定詞可以用於防止協定訊息類型之間的名稱衝突。

package = "package" fullIdent ";"

範例

package foo.bar;

選項

選項可以用於 proto 檔案、訊息、列舉和服務中。選項可以是 protobuf 定義的選項或自訂選項。如需更多資訊，請參閱語言指南中的選項。

option = "option" optionName  "=" constant ";"
optionName = ( ident | bracedFullIdent ) { "." ( ident | bracedFullIdent ) }
bracedFullIdent = "(" ["."] fullIdent ")"
optionNamePart = { ident | "(" ["."] fullIdent ")" }

範例

option java_package = "com.example.foo";

欄位

欄位是協定緩衝區訊息的基本元素。欄位可以是一般欄位、oneof 欄位或 map 欄位。欄位具有類型和欄位編號。

type = "double" | "float" | "int32" | "int64" | "uint32" | "uint64"
      | "sint32" | "sint64" | "fixed32" | "fixed64" | "sfixed32" | "sfixed64"
      | "bool" | "string" | "bytes" | messageType | enumType
fieldNumber = intLit;

一般欄位

每個欄位都有類型、名稱和欄位編號。它可能具有欄位選項。

field = [ "repeated" | "optional" ] type fieldName "=" fieldNumber [ "[" fieldOptions "]" ] ";"
fieldOptions = fieldOption { ","  fieldOption }
fieldOption = optionName "=" constant

範例

foo.Bar nested_message = 2;
repeated int32 samples = 4 [packed=true];

Oneof 和 Oneof 欄位

oneof 由 oneof 欄位和 oneof 名稱組成。

oneof = "oneof" oneofName "{" { option | oneofField } "}"
oneofField = type fieldName "=" fieldNumber [ "[" fieldOptions "]" ] ";"

範例

oneof foo {
    string name = 4;
    SubMessage sub_message = 9;
}

Map 欄位

map 欄位具有鍵類型、值類型、名稱和欄位編號。鍵類型可以是任何整數或字串類型。

mapField = "map" "<" keyType "," type ">" mapName "=" fieldNumber [ "[" fieldOptions "]" ] ";"
keyType = "int32" | "int64" | "uint32" | "uint64" | "sint32" | "sint64" |
          "fixed32" | "fixed64" | "sfixed32" | "sfixed64" | "bool" | "string"

範例

map<string, Project> projects = 3;

保留字

reserved 語句宣告在此訊息中不能使用的欄位編號或欄位名稱範圍。

reserved = "reserved" ( ranges | strFieldNames ) ";"
ranges = range { "," range }
range =  intLit [ "to" ( intLit | "max" ) ]
strFieldNames = strFieldName { "," strFieldName }
strFieldName = "'" fieldName "'" | '"' fieldName '"'

範例

reserved 2, 15, 9 to 11;
reserved "foo", "bar";

頂層定義

列舉定義

列舉定義由名稱和列舉主體組成。列舉主體可以具有選項、列舉欄位和 reserved 語句。

enum = "enum" enumName enumBody
enumBody = "{" { option | enumField | emptyStatement | reserved } "}"
enumField = ident "=" [ "-" ] intLit [ "[" enumValueOption { ","  enumValueOption } "]" ]";"
enumValueOption = optionName "=" constant

範例

enum EnumAllowingAlias {
  option allow_alias = true;
  EAA_UNSPECIFIED = 0;
  EAA_STARTED = 1;
  EAA_RUNNING = 2 [(custom_option) = "hello world"];
}

訊息定義

訊息由訊息名稱和訊息主體組成。訊息主體可以具有欄位、巢狀列舉定義、巢狀訊息定義、選項、oneof、map 欄位和 reserved 語句。在同一個訊息結構描述中，一個訊息不能包含兩個名稱相同的欄位。

message = "message" messageName messageBody
messageBody = "{" { field | enum | message | option | oneof | mapField |
reserved | emptyStatement } "}"

範例

message Outer {
  option (my_option).a = true;
  message Inner {   // Level 2
    int64 ival = 1;
  }
  map<int32, string> my_map = 2;
}

在訊息內宣告的實體都不能有衝突的名稱。以下所有情況皆為禁止：

message MyMessage {
  optional string foo = 1;
  message foo {}
}

message MyMessage {
  optional string foo = 1;
  oneof foo {
    string bar = 2;
  }
}

message MyMessage {
  optional string foo = 1;
  enum E {
    foo = 0;
  }
}

服務定義

service = "service" serviceName "{" { option | rpc | emptyStatement } "}"
rpc = "rpc" rpcName "(" [ "stream" ] messageType ")" "returns" "(" [ "stream" ]
messageType ")" (( "{" {option | emptyStatement } "}" ) | ";")

範例

service SearchService {
  rpc Search (SearchRequest) returns (SearchResponse);
}

Proto 檔案

proto = [syntax] { import | package | option | topLevelDef | emptyStatement }
topLevelDef = message | enum | service

.proto 檔案範例

syntax = "proto3";
import public "other.proto";
option java_package = "com.example.foo";
enum EnumAllowingAlias {
  option allow_alias = true;
  EAA_UNSPECIFIED = 0;
  EAA_STARTED = 1;
  EAA_RUNNING = 1;
  EAA_FINISHED = 2 [(custom_option) = "hello world"];
}
message Outer {
  option (my_option).a = true;
  message Inner {   // Level 2
    int64 ival = 1;
  }
  repeated Inner inner_message = 2;
  EnumAllowingAlias enum_field = 3;
  map<int32, string> my_map = 4;
}