JSON Mapping - JSON映射
Proto3支持JSON中的规范编码,使得在系统之间共享数据更加容易。下表按类型对编码进行了描述。
如果JSON编码的数据中缺少一个值或者它的值为null,那么在解析到协议缓冲区时,它将被解释为适当的默认值。如果某个字段在协议缓冲区中有默认值,则在JSON编码的数据中默认会省略该字段以节省空间。一个实现可以提供在JSON编码的输出中使用默认值发出字段的选项。
proto3 | JSON | JSON example | 描述【译】 |
---|---|---|---|
message | object | {"fooBar": v, |
生成JSON对象。消息字段名被映射到lowerCamelCase并成为JSON对象键。如果指定了json_name 选项,则指定的值将用作键。解析器接受小驼峰命秘法名称(或由json_name 选项指定的名称)和原始proto字段名称。null是所有字段类型的可接受值,并被视为相应字段类型的默认值。 |
enum | string | "FOO_ |
使用proto中指定的枚举值的名称。解析器接受枚举名和整数值。 |
map<K,V> | object | {"k": v, |
所有键都转换为字符串。 |
repeated V | array | [v, |
null被接受为空列表[]。 |
bool | true, false | true, |
|
string | string | "Hello World!" |
|
bytes | base64 string | "YWJjMTIzIT8kKiYoKSctPUB+" |
JSON值将是使用带填充的标准base64编码的字符串编码的数据。包含或不包含填充的标准或url安全base64编码都可以接受。 |
int32, fixed32, uint32 | number | 1, |
JSON值将是一个十进制数。可接受数字或字符串。 |
int64, fixed64, uint64 | string | "1", |
JSON值将是十进制字符串。可接受数字或字符串。 |
float, double | number | 1. |
JSON值将是一个数字或特殊字符串值"NaN", "Infinity",和"-Infinity"中的一个。数字或字符串都可以接受。指数符号也被接受。-0被认为等于0。 |
Any | object |
{"@type": "url", |
如果`Any`类型包含一个具有特殊JSON映射的值,它将按如下方式转换:{"@type":xxx,"value":yyy} 。否则,该值将转换为JSON对象,并插入“@type”字段以指示实际的数据类型。 |
Timestamp | string | "1972-01-01T10:00:20. |
使用RFC3339,其中生成的输出将始终是**Z**规格化的,并使用0、3、6或9个小数位数。也接受“Z”以外的偏移。 |
Duration | string | "1. |
生成的输出总是包含0、3、6或9个小数位数(取决于所需的精度),后跟“s”后缀。接受任何小数位数(没有小数也可以),只要它们符合纳秒精度,并且需要“s”后缀。 |
Struct | object |
{ … } |
任何JSON对象。见struct.proto 。 |
Wrapper types | various types | 2, |
包装器在JSON中使用与包装原语类型相同的表示形式,只是在数据转换和传输期间允许并保留null。 |
FieldMask | string | "f. |
见field_mask.proto |
ListValue | array | [foo, |
|
Value | value | 任何JSON值。详见google.protobuf.Value | |
NullValue | null | JSON null | |
Empty | object | {} |
空的JSON对象 |
JSON选项
proto3
的JSON实现可以提供以下选项:
- 发出具有默认值的字段:在proto3 JSON输出中,带有默认值的字段默认省略。该实现可以提供一个选项来覆盖这个行为并用它们的默认值输出字段。
- 忽略未知字段:proto3 JSON解析器在默认情况下应该拒绝未知字段,但是可以提供一个在解析中忽略未知字段的选项。
- 使用proto字段名而不是lowerCamelCase名称:默认情况下,proto3 JSON打印器应将字段名转换为lowerCamelCase并将其用作JSON名称。一个实现可以提供一个使用proto字段名作为JSON名称的选项。proto3 JSON解析器需要同时接受转换后的lowerCamelCase名称和proto字段名称。
- 以整数而不是字符串的形式发出枚举值:默认情况下,在JSON输出中使用枚举值的名称。可以提供一个选项来使用枚举值的数值。