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，

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类型

protocal buffer