protobuf文档翻译-安装，数据格式及编码规范

Install

Download protobuf: https://github.com/protocolbuffers/protobuf/releases

unzip protoc-3.8.0-linux-x86_64.zip 
sudo cp -r include/* /usr/local/include/
sudo cp bin/protoc /usr/local/bin/

Download Go support for protobuf:

go get -u github.com/golang/protobuf/protoc-gen-go

Download faster and also more customizable Go support:

go get github.com/gogo/protobuf/protoc-gen-gofast

Proto2.0

每个proto文件中可以定义一组message。为了防止依赖关系等泛滥，一般只在一个proto文件中定义一组相关联的message。

定义一个message

message SomeMessage {
    [required|optional] type fieldName = fieldNumber [default=10];
}

fieldNumber 从1开始。

注释

注释的语法和C++相同：

/* 这是一段注释 */
// 这也是一段注释

保留字段(Reserved Fields)

当一个字段被删除后，后续的用户可以重新使用这个字段数字或名字， 就导致proto迁移过程中可能造成一些潜藏的bug。可以通过保留声明他们，
将来如果有用户重用了这些字段，就会报错：

message Foo {
    reserved 2, 15, 9 to 11;
    reserved "foo", "bar";
}

数据类型

proto 注释 Go Python C++ Java
double *float64 float double double
float *float32 float float float
int32 编码长度是可变的，不能用于编码负数。如果要用于负数，应当使用sint32 *int32 int int32 int
int64 类似int32,应当使用sint64编码负数 *int64 int/log int64 long
uint32 变长编码 *uint32 int/long uint32 int
uint64 变长编码 *uint64 int/long uint64 long
sint32 变长编码 *int32 int int32 int
sint64 变长编码 *int64 int/long int64 long
fixed32 4字节，比uint32更适合编码超过2^28的数字 *uint32 int/long uint32 int
fixed64 8字节，2^56 *uint64 int/long uint64 long
sfixed32 4字节 *int32 int int32 int
sfixed64 8字节 *int64 int/long int64 long
bool *bool bool bool boolean
string 必须是UTF-8编码或是7bit的ASCII *string unicode(Py2), str(Py3) string String
bytes 可以包含任意byte序列 []byte bytes string ByteString

注意： 当说到更适合，或应当使用时，并不是说这个类型的表达范围不能够比得上另一种类型，而是其编码长度更有效率。

可选字段和默认值

一个message中可以设定一个字段为optional，当消息解码时发现该字段缺席，就会按照默认值（default）给定值，否则给定该类型的默认值（类似Go）,枚举类型则会使用第一个枚举值。

形如：

optional int32 result_per_page = 3 [default=10];

枚举类型

枚举类型使用的是32位整形数，如果使用了负数，编码效率会变低。

enum Corpus {
    UNIVERSAL = 0;
    WEB = 1;
    IMAGES = 2;
}

枚举类型中默认第二个值是不能重复的，如果要有重复，那么就要指定允许别名：

enum State {
    option allow_alias = true;
    UNKNOWN = 0;
    STARTED = 1;
    RUNNING = 1;
}

保留枚举

如果你删除了枚举中的一个值，那么以后别人就可以重新用它们。可以这样保留这些字段：

enum Foo {
    reserved 2, 15, 9 to 11, 40 to max;
    reserved "FOO", "BAR";
}

导入定义

import "myproject/other_proto.proto"
import public "new.proto"

要想让protoc找到它们，需要通过 -I 或 --proto_path 来定义，一般是将项目根目录作为 --proto_path 参数。

类型嵌套

message SearchResponse {
    message Result {
        required string url = 1;
        optional string title = 2;
        repeated string snippets = 3;
    }
    repeated Result result = 1;
}

message SomeOtherMessage {
    optional SearchResponse.Result result = 1; // 从外部引用一个嵌套类型
}

Proto3.0

syntax = "proto3";

message SearchRequest {
    string query = 1;
    int32 page_number = 2;
    int32 result_per_page = 3;
}
  • singular: 0或1个该字段
  • repeated: 可以出现0到多个该字段

proto3中数字类型默认使用packed编码

类型更新

  • 不要更改任何现有字段的field number
  • 旧message的默认值应当保持不变
  • 字段可以移除，在该field number不再使用的前提下
  • int32/uint32/int64/uint64/bool 是兼容的，可以任意修改类型，但是可能会出现精度问题等
  • sint32与sint64 兼容，但不与其它类型兼容
  • string和bytes兼容，前提是它们都是有效的UTF-8编码
  • 如果bytes包含了编码的message，嵌套message与bytes兼容
  • fixed32 与 sfixed32/fixed64/sfixed64兼容
  • enum与 int32/uint32/int64/uint64兼容
  • 把单个字段放入一个新的oneof是安全且兼容的；把多个字段放入一个新的oneof 可能 是安全且兼容的，如果你确认没有代码同时设定这多个字段的前提下。 把任何字段放入一个现存的oneof是不安全兼容的。

未知字段

由于proto版本兼容问题，导致旧的废弃字段不能被使用，proto3开始时会直接丢弃它们，但从3.5开始将它们保留

任意类型

任意类型 Any 本质上就是序列化好的bytes类型， 使用该类型需要引入 google/protobuf/any.proto:

import "google/protobuf/any.proto";

message ErrorStatus {
    string message = 1;
    repeated google.protobuf.Any details = 2;
}

Oneof

如果message中有若干字段，一次最多只会设置其中的一个字段，那么就可以通过oneof来约定这种关系，类似于C语言的union：

message SampleMessage {
    oneof test_oneof {
        string name = 4;
        SubMessage sub_message = 9;
    }
}

oneof 的向后兼容

如果检查一个oneof的值返回 None/NOT_SET, oneof可能没有设置值，也可能是版本不同，但我们无法断定这件事。

Maps

map<key_type, value_type> map_field = N;
  • map类型字段不可以是 repeated
  • 遍历顺序/传输序列化顺序是不可知的
  • 从map专程text格式时会对key做排序
  • 从传输数据传入或合并时，如果map中的key存在重复，使用最后一个，从text格式处理map时，如果key重复会导致失败
  • 如果只提供key但不提供值，那么序列化行为随语言而定

Map类型在传输时等价于：

message MapFieldEntry {
    key_type key = 1;
    value_type value = 2;
}

repeated MapFieldEntry map_field = N;

Packages

package foo.bar;
message Open { ... }

message Foo {
    foo.bar.Open open = 1;
}

在Go中这会被当成包名

Services

service SearchService {
    rpc Search (SearchRequest) returns (SearchResponse);
}

Options

options不会修改数据定义，但是会影响一些语言生成的行为等等。

optimize_for

这是一个文件级选项，用于设定生成代码的优化方向。

optimize_for [SPEED|CODE_SIZE|LITE_RUNTIME]

SPEED: 默认值，优先生成高效编解码的代码
CODE_SIZE: 利用反射等语言特性生成体积小的代码，但操作可能会更慢
LITE_RUNTIME: 使用一个体积更小，也更少特性（如反射）的运行时来进行编解码

deprecacted

字段选项，用于暗示字段已弃用，新代码不应当再使用它。Java中会加入@Deprecated，其它语言暂不支持。

自定义选项

protobuf允许自定义选项，虽然大部分情况用不上： https://developers.google.com/protocol-buffers/docs/proto.html#extensions

JSON

protobuf 提供了JSON输出格式，部分类型可能与想象有所不同：

proto3 JSON JSON Example Notes
enum string "FOO_BAR" 默认使用枚举的名字，不过处理时使用int值也是可以的
map<K,V> object {"k1":v1,...} 所有的key都会被转换成字符串
repeated V array [v1, ...] null 会被解析城空的列表
bytes base64 string "YWJjMT..." 编码时会自动使用带padding的标准Base64编码成字符串
int32/fixed32/uint32 number 1, -10, 0 JSON值会是一个10进制数字，解析时数字或者字符串都可以接受
int64/fixed64/uint64 string "1", "-10" 由于64位整数已经超出了JSON number的表示范围，编码解码都是用string
float/double number 1.1, -10.0, "NaN", "Infinity","-Infinity" 编码时会被做成number或特殊字符串，解码时数字或字符串都可以
Any object {"@type":"url", "f": v, ...} @type暗示了真实的数据类型，如果Any中包含了一个值是特定的原生JSON数据，则会直接被解析出来 {"@type": xxx, "value": yyy}
Timestamp string "1972-01-01T10:00:20.021Z" RFC3339,尾部小数点后可以有0,3,6,9位数字
Duration string "1.0002s", "1s" 尾部必须是s结尾，前面可以使用很多小数精度，但精度范围要在纳秒范围内
struct object {...} see struct.proto
包装类型（别名） 与实际对应的类型行为保持一致
Empty object {} 空对象
NullValue null JSON null

在渲染JSON时，默认proto3不会输出值与默认值相等的字段，除非特别通过option指定

使用protoc

protoc --proto_path=IMPORT_PATH --cpp_out=DST_DIR --java_out=DST_DIR --python_out=DST_DIR --go_out=DST_DIR --ruby_out=DST_DIR --objc_out=DST_DIR --csharp_out=DST_DIR path/to/file.proto

编码规范

文件名使用蛇形：

lower_snake_case.proto

文件格式

  • 一行最长80字符
  • 2空格缩进

文件结构

  1. License header
  2. File overview
  3. Syntax
  4. Package
  5. Imports (sorted)
  6. File options
  7. Everything else

重复字段（数组）

使用复数形式：

repeated string keys = 1;
repeated MyMessage accounts = 17;

枚举

枚举使用C语言的标准形式：全大写，下划线

Service

Service使用CamelCase

需要避免的

required和groups,这是给proto2用的，proto3不需要

【推广】 免费学中医，健康全家人
原文地址：https://www.cnblogs.com/qianyuming/p/10955822.html