proto3 协议指引

一、protocal buffer 是什么？

一种序列化机制。

什么是序列化？

一种转化为可存储和传输对象的过程。

序列化的方式有很多，那么proto有什么特殊的呢？

它的英文介绍里提到了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且不可重复。通常考虑到向后兼容的因素，不建议修改已定义的字段序号。

需要注意的是，序号大小会影响序列化编码的空间占用，例如：

序号范围[1,15]：proto使用1个字节存储字段的序号及类型，适宜定义常用字段。

序号范围 [16,2047]：proto使用2个字节存储字段的序号及类型。

...

序号可用域[1,2²⁹ - 1]，其中[19000,19999]为proto保留序号范围（编译使用），不可使用。另外，开发方可以约定保留序号，以供扩展或其它特殊使用。

2、字段约束

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	四字节空间占用。存储值>2²⁸时，存储效率高于uint32。	int^[1]
fixed64	八字节空间占用。存储值>2⁵⁶时，存储效率高于uint64。	long^[1]
sfixed32	四字节空间占用	int
sfixed64	八字节空间占用	long
bool		boolean
string	UTF-8编码或者7位ASCII文本，长度不可超过2³²	String
bytes	可以存储任何二进制数据，长度不可超过2³²	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 类型

定义如下：

map<key_type, value_type> map_field = N。

key_type：任何整形或者string类型。

value_type：可以为除了Map类型外的任何类型。