protocal buffer 定义（Java）
protobuf是一个序列化结构化数据的工具：
- 语言无关
- 平台无关
- 强扩展性
install protobuf
install protobuf主要分为两个步骤：
install compiler （protobuf 编译器，用来编译
.proto文件）protobuf runtime (根据使用不同的语言来安装不同的runtime）
install compiler
protobuf compiler可以直接在github中下载获得。在链接中可以找到对应的zip包：protoc-$version-$platform.zip。根据自己需要使用的compiler的版本（version）以及使用compiler的操作系统（platform）下载对应的zip包。
protobuf runtime
根据不同的编程语言，需要使用不同的runtime。因为对Java比较熟悉所以所有的例子都是基于Java的，其中Java使用runtime的的方式。
指南
定义proto文件/解析proto文件
// [START declaration]
// 使用的proto的语法定义版本
syntax = "proto3";
// 包声明，防止不同项目之间冲突
// 在java中，默认会作为java的package name（除非特殊指定了java_package）
package tutorial;
import "google/protobuf/timestamp.proto";
// [END declaration]
// [START java_declaration]
// 生成的Java代码所在的package
option java_package = "com.example.tutorial";
// 是否生成多个Java文件
option java_multiple_files = true;
// 生成的Java的类文件的名字
option java_outer_classname = "AddressBookProtos";
// [END java_declaration]
// [START csharp_declaration]
option csharp_namespace = "Google.Protobuf.Examples.AddressBook";
// [END csharp_declaration]
// [START messages]
message Person {
string name = 1;
int32 id = 2; // Unique ID number for this person.
string email = 3;
enum PhoneType {
MOBILE = 0;
HOME = 1;
WORK = 2;
}
message PhoneNumber {
string number = 1;
PhoneType type = 2;
}
repeated PhoneNumber phones = 4;
google.protobuf.Timestamp last_updated = 5;
}
// Our address book file is just one of these.
message AddressBook {
repeated Person people = 1;
}
// [END messages]
- tag id，用来对field进行编码。tag从1-15需要less than one byte，所以如果是一些经常被使用的field或者
repeatedfield尽量使用1-15。把16或者16以上的tag留给不经常使用或者optionl的field - field annotation（proto2中才需要定义required和optional)
- required：初始化一个message，对应的field必须被提供，不然会出现因为
uninitialized导致的RuntimeException问题。parse 一个uninitialized将会抛出IOException异常。 - optional：可以set或者不set，如果不set就使用default value。
- repeated：field会重复出现0到多次，protobuf会保存每一个value的order，
- required：初始化一个message，对应的field必须被提供，不然会出现因为
protobuf API
在一个proto文件中定义的各种message（包含nested的message）都会在生成的Java文件中有对应的一个Class，以及每一个Class都要一个Builder Class来帮助我们初始化一个message对应的Class。
Message和Builder都有各自的访问field的方法：
Message只有get方法。当以个Message的object被创建以后是不允许被修改的。创建一个Message对象首先需要创建一个builder，然后set需要的field，然后调用builder's的build方法。
builder有get和set方法
语法定义
Message的数据类型
scalar value type（标量类型）proto中支持的有：double float int32 int64 bool string bytes（java中用bytestring支持），还有其他类型
符合类型
Field的类型
singular 单一的类型
repeated
enum类型
constant必须从0开始
如果在其他enum中使用了同样的constant，需要使用option allow_alias = true
其他message type
message SearchResponse {
repeated Result results = 1;
}
message Result {
string url = 1;
string title = 2;
repeated string snippets = 3;
}
import definition
import 其他 proto中定义的message
如果import的proto位置发生了变动，就需要使用一个proto来指向新的proto；import public
nested type，嵌套类型
更新 message
这是一个非常重要的内容，如果以后在设计一些内容，但是中间需要修改，又不想影响其他服务的情况下。
链接
Any type
import google/protobuf/any.proto
Oneof 类型
一个message中有多个field，但是at most one field会被使用
Setting any member of the oneof automatically clears all the other members.
Map 类型
map<key_type, value_type> map_field = N;
其中的key_type只能是标准类型，并且不能是float类型和bytes类型。value_type不能是repeated类型
