一种序列化机制。
一种转化为可存储和传输对象的过程。
它的英文介绍里提到了neutral这个词,中立,无关的。
language-neutral 跨语言:它可以应用于多种开发语言之间数据交互。
platform-neutral 跨平台:它可以运行于多种系统平台。
可扩展
序列化过程性能优越,速度快。
序列化后为二进制数据,相对的占用空间更小(存储成本及传输成本)及一定程度的保障数据的安全性。
提供支持多语言的自动化代码生成工具,开发易用性。
proto3 文件:.proto
syntax = "proto3";
message SearchRequest {
string query = 1;
int32 page_number = 2;
int32 result_per_page = 3;
}
第一行声明当前使用的proto3版本协议语法(proto编译器默认使用proto2版本协议语法),声明必须为文件的第一行,此前不能有任何内容,包括注释。
消息使用“message”关键字定义,内部以“字段类型 字段名称 = 字段序号;”形式定义所要包含额属性。
每一个字段被赋予一个唯一的序号,起始为1且不可重复。通常考虑到向后兼容的因素,不建议修改已定义的字段序号。
需要注意的是,序号大小会影响序列化编码的空间占用,例如:
序号范围[1,15]:proto使用1个字节存储字段的序号及类型,适宜定义常用字段。
序号范围 [16,2047]:proto使用2个字节存储字段的序号及类型。
...
序号可用域[1,229 - 1],其中[19000,19999]为proto保留序号范围(编译使用),不可使用。另外,开发方可以约定保留序号,以供扩展或其它特殊使用。
singular:更直观的可以用optional来释义,可选字段,0个或1个,proto3中未默认约束。
repeated:列表集合字段类型,可以包含 >=0 个字段元素。
proto3编码类型对应不同开发语言数据类型:
.proto Type | 说明 | Java Type |
---|---|---|
double | double | |
float | float | |
int32 | 使用可变长编码。 对于负数编码效率较低(可以使用sint32类型存储) | int |
int64 | 使用可变长编码。 对于负数编码效率较低(可以使用sint64类型存储) | long |
uint32 | 使用可变长编码。 | int[1] |
uint64 | 使用可变长编码。 | long[1] |
sint32 | 使用可变长编码,存储有符号整数。尤其对负数编码效率更高。 | int |
sint64 | 使用可变长编码,存储有符号整数。尤其对负数编码效率更高。 | long |
fixed32 | 四字节空间占用。存储值>228时,存储效率高于uint32。 | int[1] |
fixed64 | 八字节空间占用。存储值>256时,存储效率高于uint64。 | long[1] |
sfixed32 | 四字节空间占用 | int |
sfixed64 | 八字节空间占用 | long |
bool | boolean | |
string | UTF-8编码或者7位ASCII文本,长度不可超过232 | String |
bytes | 可以存储任何二进制数据,长度不可超过232 | ByteString |
singular 类型字段在进行编解码时,如果没有进行赋值则赋予默认值。不同类型使用默认值如下:
类型 | 默认值 |
---|---|
string | 空字符串 |
bytes | 空byte数组 |
bool | false |
数值类型 | 0 |
enums | 定义的枚举第一个元素(默认必须为0) |
定义的message类型 | 不赋值 |
repeated * | 空列表 |
proto3关于默认值的操作,在我们实际的使用中不免会造成一些困扰,我们需要去区分未知结果和默认值结果两者之间的区别。例如,我们定义了bool类型字段updated(是否已更新),默认的false所表示未更新,则会将未知是否已更新覆盖。
对于此,通常处理的方式是引入包装类型wrapper,使用如下:
import "google/protobuf/wrappers.proto";
wappers.proto文件定义如下:
// Protocol Buffers - Google's data interchange format
// Copyright 2008 Google Inc. All rights reserved.
// https://developers.google.com/protocol-buffers/
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
// * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// Wrappers for primitive (non-message) types. These types are useful
// for embedding primitives in the `google.protobuf.Any` type and for places
// where we need to distinguish between the absence of a primitive
// typed field and its default value.
//
// These wrappers have no meaningful use within repeated fields as they lack
// the ability to detect presence on individual elements.
// These wrappers have no meaningful use within a map or a oneof since
// individual entries of a map or fields of a oneof can already detect presence.
syntax = "proto3";
package google.protobuf;
option csharp_namespace = "Google.Protobuf.WellKnownTypes";
option cc_enable_arenas = true;
option go_package = "github.com/golang/protobuf/ptypes/wrappers";
option java_package = "com.google.protobuf";
option java_outer_classname = "WrappersProto";
option java_multiple_files = true;
option objc_class_prefix = "GPB";
// Wrapper message for `double`.
//
// The JSON representation for `DoubleValue` is JSON number.
message DoubleValue {
// The double value.
double value = 1;
}
// Wrapper message for `float`.
//
// The JSON representation for `FloatValue` is JSON number.
message FloatValue {
// The float value.
float value = 1;
}
// Wrapper message for `int64`.
//
// The JSON representation for `Int64Value` is JSON string.
message Int64Value {
// The int64 value.
int64 value = 1;
}
// Wrapper message for `uint64`.
//
// The JSON representation for `UInt64Value` is JSON string.
message UInt64Value {
// The uint64 value.
uint64 value = 1;
}
// Wrapper message for `int32`.
//
// The JSON representation for `Int32Value` is JSON number.
message Int32Value {
// The int32 value.
int32 value = 1;
}
// Wrapper message for `uint32`.
//
// The JSON representation for `UInt32Value` is JSON number.
message UInt32Value {
// The uint32 value.
uint32 value = 1;
}
// Wrapper message for `bool`.
//
// The JSON representation for `BoolValue` is JSON `true` and `false`.
message BoolValue {
// The bool value.
bool value = 1;
}
// Wrapper message for `string`.
//
// The JSON representation for `StringValue` is JSON string.
message StringValue {
// The string value.
string value = 1;
}
// Wrapper message for `bytes`.
//
// The JSON representation for `BytesValue` is JSON string.
message BytesValue {
// The bytes value.
bytes value = 1;
}
enum 枚举对象 {
UNKOWN = 0; //默认值机制使用(首先必须有一个枚举值为0的枚举实例,其次兼容proto2中使用第一个变量为默认值的机制)
枚举实例 = 枚举值;
... ...
}
1、不可修改已定义的字段序号。
2、可以删除已定义的字段,但是其序号不可在被使用。
3、int32, uint32, int64, uint64及bool是相互兼容的,只不过转换过程会产生值域变更。
4、sint32 和 sint64 是相互兼容的。
5、byte3存储值为有效UTF-8编码内容时与string相互兼容。
未能对应解析的字段会存储于未知字段中。此机制在proto3中最初抛弃,v3.5版本重新引入。
定义如下:
map<key_type, value_type> map_field = N。
key_type:任何整形或者string类型。
value_type:可以为除了Map类型外的任何类型。