Protobuf

[wxb]

Protobuf

PB 是一种语言无关、平台无关 用于序列化结构化数据的可扩展机制

Protobuf提供了一种语言无关、平台无关、可扩展的机制，以向前兼容和向后兼容的方式序列化结构化数据。它类似于JSON，只不过它更小、更快，而且它生成原生的语言绑定。你只需要定义一次你想要的数据结构，然后你就可以很容易的生成读写数据的各种语言代码

Protobuf是定义语言，proto编译器生成数据访问、语言特定运行时库和文件（或网络）上的数据序列化代码

PB 解决了什么问题？

Protobuf为大小不超过几兆字节的类型化、结构化的数据包提供了一种序列化格式。这种格式既适合短期的网络流量，也适合长期的数据存储。可以使用新信息扩展Protobuf，而不会使现有数据无效或要求更新代码。

Protobuf的消息和服务定义在.proto文件中，如下是一个消息定义示例：

message Person {
  optional string name = 1;
  optional int32 id = 2;
  optional string email = 3;
}

proto编译器构建时通过读取.proto文件的定义生成目标语言代码。生成代码包含字段访问器和数据的序列化和解析方法。如下是生成方法的使用示例：

Person john = Person.newBuilder()
    .setId(1234)
    .setName("John Doe")
    .setEmail("[email protected]")
    .build();
output = new FileOutputStream(args[0]);
john.writeTo(output);

protobuf 保持向后兼容性至关重要。protobuf允许在不破坏现有服务的情况下无缝支持任何更改，包括添加新字段和删除现有字段。有关此主题的更多信息，请参阅Updating Proto Definitions Without Updating Code。

PB 使用的好处是什么？

• 优点

  • Protobuf语言无关、平台无关和可扩展
  • 序列化 类型化、结构化的数据
  • 最常用于定义通信协议(与gRPC一起)和数据存储
  • 紧凑数据存储
  • 快速解析
  • 多编程语言的可用
  • 可自动生成经过优化的功能代码类

• 跨语言兼容
  用任何受支持的编程语言编写的代码都可以读取相同的消息。

  • pb编译器protoc直接支持的语言包括：C++、C#、Java、Python、kotlin、Objective-C、php、Ruby
  • 由Google支持的语言：Go、Dart
  • 其他语言的支持请参考：Third-Party Add-ons for Protocol Buffers.

• 跨项目支持

• 更新PB原型定义而不更新代码

• PB不适合做什么

谁使用PB？

很多项目在使用，例如这些：

• gRPC
• Google Cloud
• Envoy Proxy

PB 是如何工作的？

PB 定义语法

更多的数据类型支持

PB 开源哲学

PB 的历史

开发者社区

其他资源

[wxb]

语言指南 (proto 2)

[wxb]

语言指南 (proto 3)

定义一个消息类型

syntax = "proto3";

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 results_per_page = 3;
}

• pb文件第一行指定使用proto3语法：
  • 这个定义必须是文件的第一个非空、非注释行
  • 如果没有指定，编译器假定使用proto2语法
• 消息类型定义中包含承载数据的字段，每个字段包含：
  • 字段类型
  • 字段名
  • 字段编号

1.1 指定字段类型

1.2 分配字段编号

1.3 指定字段标签

• optional: 一个optional（可选）字段有以下两种可能得状态
  • 字段已设置，并且包含显示设置的值或者从wire解析的值。该字段将被序列化到wire上
  • 字段未设置，将返回默认值。该字段不会被序列化到wire上
• repeated:
• map:

Maps

protobuf创建map语法

map<key_type, value_type> map_field = N;

• Map类型字段不能是repeated（也就是没法定义对象数组）

[wxb]

Protobuf风格指南

原则：尊重现有风格，关键是一致性

1. 文件格式

• 保持单行80个字符长度
• 使用2个空格进行缩进
• 字符串使用双引号

2. 文件结构

• pb文件名应该以小写蛇形形式命名：lower_snake_case.proto
• pb文件应该按照下面的顺序进行管理：
  1. 头部证书申明（如果有）
  2. 文件概述
  3. Syntax 申明
  4. Package 申明
  5. Imports 映入文件
  6. options
  7. 其他代码

3. Packages

• package名 应该小写
• package名 应该是当前项目下唯一的
• 可能的话应该是pb类型定义文件路径的一部分

4. Message 和 field 名

• 使用驼峰形式（首字母大写）作为message名；例如：SongServerRequest
• 使用小写蛇形形式（underscore_separated_names）作为field名（包括 oneof字段和扩展名）；例如：song_name

  message SongServerRequest {
    optional string song_name = 1;
  }

• 字段使用这样的命名惯例，桩代码将包含如下的访问器：

  Go:
   func (x *SongServerRequest) GetSongName() string {
  
  Java:
    public String getSongName() { ... }
    public Builder setSongName(String v) { ... }

• 字段包含数字，数字应该出现在字母之后，而不是下划线之后；例如：应该用song_name1 代替song_name_1

5. Repeated 字段

使用复数名作为 rpeated 字段名

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

6. Enums 枚举

• 使用驼峰形式（首字母大写）作为enum枚举类型名
• 使用下划线分隔的全大写作为值的名字
• 每一个枚举值应该以分号结尾，而不是逗号
• 倾向于单独列出enum枚举值，而不是将枚举值放在封闭的message中
• 枚举零值应该包含UNSPECIFIED （未指明）后缀

enum FooBar {
  FOO_BAR_UNSPECIFIED = 0;
  FOO_BAR_FIRST_VALUE = 1;
  FOO_BAR_SECOND_VALUE = 2;
}

7. Services 服务

• 使用驼峰形式（首字母大写）作为RPC服务名
• 使用驼峰形式（首字母大写）作为RPC服务方法名

service FooService {
  rpc GetSomething(GetSomethingRequest) returns (GetSomethingResponse);
  rpc ListSomething(ListSomethingRequest) returns (ListSomethingResponse);
}

8. 要避免的注意项

• required 关键字（只有proto2支持）
• group 关键字（只有proto2支持）

[wxb]

Enum 枚举

[wxb]

Encoding 编码

编码描述了protobuf wire格式，它定义了如何在连接上发送消息以及它在磁盘上消耗多少空间的详细信息。理解protobuf编码知识有利于进行优化。

Protoscope是一种非常简单的语言，用于描述底层wire格式的片段，它可以为各种消息的编码提供可视化参考。

[wxb]

配图清新的Protobuf 编码&避坑指南

[wxb]

Techniques

[wxb]

第三方插件

[wxb]

Field Presence

[wxb]

Proto 最佳实践

• 不要重用标签号

  永远不要重用标签号，否则它会弄乱数据的反序列化。即使你觉得没有人使用这个字段了，也不要重用这个标签号

• 不要变更字段类型

  a. 几乎永远不改变字段的消息类型，因为同样它会弄乱数据的反序列化，就像重用标签号一样。
  b. 除非新的消息类型是旧的消息类型的超集，否则更改字段的消息类型将是破坏性的。

• 不要定义必须字段

  a. 永远不要添加一个必须（required）字段，应该添加 // required到API契约中
  b. 在proto3中，required已经被完全移除。所有字段可选（optional）或重复(repeated)

• 不要在一个消息中定义大量的字段

  不要使一个消息中定义很多字段。在C++中，无论字段是否填充都会占用一部分内存；在java中，太大的消息生成的代码甚至可能无法编译(Java中对方法的大小有硬性限制)

• 在枚举类型中定义一个未指定的默认值

  a. 枚举应该包含一个默认的 FOO_UNSPECIFIED 值作为声明中的第一个值。

• 不要用C/C++中的宏常量作为枚举值

  避免使用宏常量，如“NULL”、“NAN”和“DOMAIN”作为枚举值。否则可能会导致编译错误。

• 使用众所周知或常用的数据类型

  当一个完全合适的通用类型已经存在时，就不要再在你的代码中这样使用了：int32 timestamp_seconds_since_epoch 或 int64 timeout_millis
  强烈建议嵌入以下公共和众所周知的数据类型

  • 众所周知的数据类型

    • duration 是一个有符号、固定的时间跨度
    • timestamp 是一个独立于任何时区或日历的时间点
    • field_mask

  • 公共的数据类型

    • interval 是独立于时区或日历的时间间隔 (for example, 2017-01-15T01:30:15.01Z - 2017-01-16T02:30:15.01Z).
    • date 是一个完整的日历日期 (for example, 2005-09-19).
    • dayofweek是一周中的一天 (for example, Monday).
    • timeofday 是一天中的一个时间 (for example, 10:42:23).
    • latlng 是一个纬度/经度对 (for example, 37.386051 latitude and -122.083855 longitude).
    • money 是指具有其货币类型的货币数量 (for example, 42 USD).
    • postal_address 是一个邮政地址(for example, 1600 Amphitheatre Parkway Mountain View, CA 94043 USA).
    • color是RGBA色彩空间中的一种颜色
    • month是一年中的一个月 (for example, April).

• 将可复用的消息类型定义在单独的文件中

  考虑到消息类型会有广泛的复用时，应该将他们放在没有依赖关系的单独文件中，然后，任何人都可以轻松地使用这些类型。

• 保留已删除字段的标签号

  当删除不再使用的字段时，请保留其标记号，以便将来不会有人意外地重复使用它：reserved 2, 3;。还可以保留名称：reserved "foo", "bar";

• 保留已删除枚举值的编号

  当删除不再使用的枚举值时，请保留它的编号，以便将来不会有人意外地重用它: reserved 2, 3;。还可以保留名称：reserved "FOO", "BAR";

• 不要改变字段的默认值

  a. 几乎永远不要改变一个原型字段的默认值：否则会导致客户机和服务器之间的偏差
  b. proto3删除了设置默认值的功能

• 不要将repeated字段改为标量类型

  尽管这么改不会造成奔溃，但会丢失数据

• pb生成的代码应该遵循代码风格指南

• 永远不要使用文本格式的消息进行交换

  当二进制文件不知道字段重命名、新字段或新扩展名时，文本格式协议缓冲区的反序列化将失败。

• 永远不要依赖跨构建的序列化稳定性

[wxb]

API 最佳实践

[wxb]

jsonpb

jsonpb包提供了PB消息和JSON之间封送和解封送的功能。
遵循规范 https://developers.google.com/protocol-buffers/docs/proto3#json

索引

• func Unmarshal(r io.Reader, m proto.Message) error

• func UnmarshalNext(d *json.Decoder, m proto.Message) error

• func UnmarshalString(s string, m proto.Message) error

• type AnyResolver

• type JSONPBMarshalerDEPRECATED

• type JSONPBUnmarshalerDEPRECATED

• type Marshaler

  • func (jm *Marshaler) Marshal(w io.Writer, m proto.Message) error
  • func (jm *Marshaler) MarshalToString(m proto.Message) (string, error)

• type Unmarshaler

  • func (u *Unmarshaler) Unmarshal(r io.Reader, m proto.Message) error
  • func (u *Unmarshaler) UnmarshalNext(d *json.Decoder, m proto.Message) error

[wxb]

protojson

封送和解封protobuf消息为 JSON 格式。原理遵循规范： https://developers.google.com/protocol-buffers/docs/proto3#JSON

索引

• func Format(m proto.Message) string
• func Marshal(m proto.Message) ([]byte, error)
• func Unmarshal(b []byte, m proto.Message) error
• type MarshalOptions
  • func (o MarshalOptions) Format(m proto.Message) string
  • func (o MarshalOptions) Marshal(m proto.Message) ([]byte, error)
• type UnmarshalOptions
  • func (o UnmarshalOptions) Unmarshal(b []byte, m proto.Message) error

[wxb]

情景1：PB消息转成json时，保留未填充的字段

pb转json时有omitempty,导致转成的json字段缺失，这时自己用这个方式转

m := protojson.MarshalOptions{EmitUnpopulated: true}
jsonByte,err := m.Marshal(pbMsg)
fmt.Println(string(jsonByte), err)

[wxb]

情景2：PB消息转成json时，使用pb消息的字段名成json字段

m := protojson.MarshalOptions{UseProtoNames: true}
jsonByte,err := m.Marshal(pbMsg)
fmt.Println(string(jsonByte), err)

[wxb]

golang/proto

Package proto provides functions operating on protocol buffer messages.

[wxb]

Any类型消息 使用示例

import (
	"google.golang.org/protobuf/types/known/anypb"
	"google.golang.org/protobuf/types/known/structpb"
)

func main() {
	// 生成一个 proto.Message 消息实体
	m, _ := structpb.NewValue(map[string]interface{}{
		"firstName": "John",
		"lastName":  "Smith",
		"isAlive":   true,
		"age":       27,
		"address": map[string]interface{}{
			"streetAddress": "21 2nd Street",
			"city":          "New York",
			"state":         "NY",
			"postalCode":    "10021-3100",
		},
		"phoneNumbers": []interface{}{
			map[string]interface{}{
				"type":   "home",
				"number": "212 555-1234",
			},
			map[string]interface{}{
				"type":   "office",
				"number": "646 555-4567",
			},
		},
		"children": []interface{}{},
		"spouse":   nil,
	})
	// 转换成 proto.Message 消息实体 为 Any类型消息实体：类似于pb中定义的Any类型字段值
	any, _ := anypb.New(m)

	// 假设我们已知any对应类型时，解析any到目标类型对象
	mm := new(structpb.Value)
	e := any.UnmarshalTo(mm)

	// json输出
	bb, ee := mm.MarshalJSON()
	println("-------", string(bb), ee == nil)

	// any消息实体断言
	ok := any.MessageIs((*structpb.Value)(nil))
	println("-------", ok, mm.String(), e == nil)

	
}

参考：

• known/anypb
• known/structpb