ProtoBuf.js 使用技巧

ゝ一纸荒年。 2022-06-05 08:17 480阅读 0赞

## Protocol Buffers ##

> Protocol buffers 是一个用来序列化结构化数据的技术，支持多种语言诸如 C++、Java 以及 Python 语言，可以使用该技术来持久化数据或者序列化成网络传输的数据。相比较一些其他的 XML 技术而言，该技术的一个明显特点就是更加节省空间（以二进制流存储）、速度更快以及更加灵活。

具体参见 Google 开发文档：[https://developers.google.com/protocol-buffers/docs/overview][https_developers.google.com_protocol-buffers_docs_overview]

## ProtoBuf.js ##

上面抄的内容不是本文重点，重点是 Google 没有推出官方的 JavaScript 库，在神奇的同性交友社区 [Github][] 上，我找到了一个纯绿色无公害的 [ProtoBuf.js][] 库。它是一个由纯 JavaScript 实现构建在 [ByteBuffer.js][] 之上的 `.proto` 文件解析库，包含 Message 构建、数据序列化和反序列化等功能。

Google Protocol Buffers 传输的数据是二进制格式，JavaScript 天生不具备处理二进制数据的能力，所以要依赖 [ByteBuffer.js][] ，ByteBuffer 和 ProtoBuf 都是由同一个团队 [dcode.io][] 出品，ByteBuffer 可以单独使用，兼容 IE8+。

## `.proto` 文件 ##

`.proto` 文件是 Protocol Buffers 的结构化数据定义，结构化数据被称为 Message，具体的就不解释了，可以看最末的两篇参考文章。

ProtoBuf.js 可以解析 `.proto`，构建 Message 对象，实现数据的序列化和反序列化，对于 `.proto` 不了解可以看官方文档：[https://developers.google.com/protocol-buffers/docs/proto3][https_developers.google.com_protocol-buffers_docs_proto3]

下面举几个例子简单说明：

`.proto`文件初始化和构建 Message，例子参见：[https://github.com/dcodeIO/ProtoBuf.js/blob/master/examples/websocket/www/index.html][https_github.com_dcodeIO_ProtoBuf.js_blob_master_examples_websocket_www_index.html]

对于声明了 package 的`.proto`，只需在构建时把包名带上就行。

使用`loadProtoFile()`会让`.proto`文件明文暴露，所以可以使用 ProtoBuf.js 提供的工具将`.proto`转义成 `json` 或 `js`，参见：[https://github.com/dcodeIO/ProtoBuf.js/wiki/pbjs][https_github.com_dcodeIO_ProtoBuf.js_wiki_pbjs]

安装 node 模块：

以 [example.proto][] 为例，在终端执行：

会输出：

<table style="width:1168px; background:0px 0px; border-collapse:collapse; border-spacing:0px; display:block; overflow-y:hidden; overflow-x:auto"> 
 <tbody> 
 <tr> 
 <td style="border-bottom:none; padding:0.3em 0.5em; border-top:none; border-right:1px solid rgb(217,217,217); border-left:none; margin:0px"> <pre style="border:none; padding:0px; margin-top:0px; margin-bottom:0px">1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
</pre> </td> 
 <td style="border:none; padding:0.3em 0.3em 0.3em 1em; margin:0px"> <pre style="border:none; padding:0px; margin-top:0px; margin-bottom:0px">var _root = dcodeIO.ProtoBuf.newBuilder({})['import']({
 
 "package": null,
 "messages": [
 {
 
 "name": "Message",
 "fields": [
 {
 
 "rule": "required",
 "type": "string",
 "name": "text",
 "id": 1
 }
 ]
 }
 ]
}).build();
</pre> </td> 
 </tr> 
 </tbody> 
</table>

在实际应用时，通常一个 `.proto` 文件里面会有很多个 Message 类型，所以会将输出结果保存为一个 builder，

<table style="width:1168px; background:0px 0px; border-collapse:collapse; border-spacing:0px; display:block; overflow-y:hidden; overflow-x:auto"> 
 <tbody> 
 <tr> 
 <td style="border-bottom:none; padding:0.3em 0.5em; border-top:none; border-right:1px solid rgb(217,217,217); border-left:none; margin:0px"> <pre style="border:none; padding:0px; margin-top:0px; margin-bottom:0px">1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
</pre> </td> 
 <td style="border:none; padding:0.3em 0.3em 0.3em 1em; margin:0px"> <pre style="border:none; padding:0px; margin-top:0px; margin-bottom:0px">var builder = dcodeIO.ProtoBuf.newBuilder({})['import']({
 
 "package": null,
 "messages": [
 {
 
 "name": "Message",
 "fields": [
 {
 
 "rule": "required",
 "type": "string",
 "name": "text",
 "id": 1
 }
 ]
 }
 ]
});
</pre> </td> 
 </tr> 
 </tbody> 
</table>

存成 builder 就可以根据需求构建 Message 类型对象，

## 序列化和反序列化 ##

在 Web 端使用 Protocol Buffers 时，无论发送还是接收的数据都应当是二进制格式，二进制数据可以直接使用 Message 类型对象解析，

<table style="width:1168px; background:0px 0px; border-collapse:collapse; border-spacing:0px; display:block; overflow-y:hidden; overflow-x:auto"> 
 <tbody> 
 <tr> 
 <td style="border-bottom:none; padding:0.3em 0.5em; border-top:none; border-right:1px solid rgb(217,217,217); border-left:none; margin:0px"> <pre style="border:none; padding:0px; margin-top:0px; margin-bottom:0px">1
2
3
4
5
6
7
8
9
10
11
12
</pre> </td> 
 <td style="border:none; padding:0.3em 0.3em 0.3em 1em; margin:0px"> <pre style="border:none; padding:0px; margin-top:0px; margin-bottom:0px">// 序列化
function encode(jsonData) {
 
 var Message = builder.build("Message");
 var msg = new Message(jsonData);
 return msg.toArrayBuffer();
}

// 反序列化
function decodeMessage(data) {
 
 var msg = builder.build("Message").decode(data);
 return msg;
}
</pre> </td> 
 </tr> 
 </tbody> 
</table>

`decode()` 返回一个 Message 实例对象（可以等同于 JSON Object），实例中的属性便是 `.proto` 文件中声明的变量与类型，

在 `.proto` 文件中声明数据类型需要遵循 [Protocol Buffers 数据类型][Protocol Buffers] 规则，如下表：  
![Protocol Buffers 数据类型][Protocol Buffers 1]

由于上图不包括 JavaScript 对应的数据类型，所以我自己补充了一个数据类型对应关系（每种数据类型我并没有一一验证使用过，可能有误，欢迎指正）：

<table style="width:1170px; border-collapse:collapse; border-spacing:0px; color:rgb(93,104,111); font-family:Merriweather,serif; font-size:15px; letter-spacing:0.15px"> 
 <thead> 
 <tr> 
 <th style="padding-bottom:0.5em; border-bottom:2px solid rgb(227,234,244)">.proto Type</th> 
 <th style="padding-bottom:0.5em; border-bottom:2px solid rgb(227,234,244)">JavaScript Type</th> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">double</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">Long</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">float</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">float</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">int32</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">int</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">int64</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">Long</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">uint32</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">int</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">uint64</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">Long</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">sint32</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">int</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">sint64</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">Long</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">fixed32</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">int</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">fixed64</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">Long</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">sfixed32</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">int</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">sfixed64</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">Long</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">bool</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">boolean</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">string</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">string</td> 
 </tr> 
 <tr> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">bytes</td> 
 <td style="border-bottom:1px solid rgb(227,234,244); padding:1rem 0px">ByteBuffer</td> 
 </tr> 
 </tbody> 
</table>

### ByteBuffer.js ###

bytes 类型是二进制格式数据，需要使用 [ByteBuffer.js][] 处理，ByteBuffer 可以直接操作二进制数据，例子：

ByteBuffer 可以直接写入或读取任意一种类型的值，值得长度为 8bits - 64bits，特殊的按位写入需要使用 JavaScript 位移操作符，比如：

更多 ByteBuffer 接口参见API：[https://github.com/dcodeIO/ByteBuffer.js/wiki/API][https_github.com_dcodeIO_ByteBuffer.js_wiki_API]

在 [Message API][] 中的 `toArrayBuffer()` `toBuffer()` 等方法底层实际调用的是 ByteBuffer 的接口，与 ByteBuffer 不同的是“Message 对象是按照 JSON 的方式修改值，调用 `toArrayBuffer()` 接口序列化数据，调用 `decode()` 接口反序列数据”。

### Long.js ###

由于 JavaScript 精度问题，所以 `int64` 和 `uint64` 等类型数据会被转换成 [Long.js][] 对象实例，Long 并不太复杂，与 [bignumber.js][] 类似，具体参考 [Long.js API][].

## WebSocket ##

关于 WebSocket 提供一个简单的[例子][https_github.com_dcodeIO_ProtoBuf.js_blob_master_examples_websocket_www_index.html]，  
实际应用与例子差不多，就是做两件基础的事：

*  连接 WebSocket，从 socket 通道拿到二进制数据，反序列化解析成 Message 对象。
 *  实例化 Message 对象，然后序列化成二进制数据，发送给服务端。

## 参考文章 ##

*  [http://www.ibm.com/developerworks/cn/linux/l-cn-gpb/][http_www.ibm.com_developerworks_cn_linux_l-cn-gpb]
 *  [http://www.cnblogs.com/royenhome/archive/2010/10/29/1864860.html][http_www.cnblogs.com_royenhome_archive_2010_10_29_1864860.html]

\--EOF-- 最后更新时间：2015-09-14 17:09:11

本文链接：[http://www.maxzhang.com/2015/09/ProtoBuf-js使用技巧/][http_www.maxzhang.com_2015_09_ProtoBuf-js]

[https_developers.google.com_protocol-buffers_docs_overview]: https://developers.google.com/protocol-buffers/docs/overview
[Github]: http://github.com/
[ProtoBuf.js]: https://github.com/dcodeIO/ProtoBuf.js
[ByteBuffer.js]: https://github.com/dcodeIO/ByteBuffer.js
[dcode.io]: http://dcode.io/
[https_developers.google.com_protocol-buffers_docs_proto3]: https://developers.google.com/protocol-buffers/docs/proto3
[https_github.com_dcodeIO_ProtoBuf.js_blob_master_examples_websocket_www_index.html]: https://github.com/dcodeIO/ProtoBuf.js/blob/master/examples/websocket/www/index.html
[https_github.com_dcodeIO_ProtoBuf.js_wiki_pbjs]: https://github.com/dcodeIO/ProtoBuf.js/wiki/pbjs
[example.proto]: https://github.com/dcodeIO/ProtoBuf.js/blob/master/examples/websocket/www/example.proto
[Protocol Buffers]: https://developers.google.com/protocol-buffers/docs/proto3#scalar
[Protocol Buffers 1]: /images/20220605/adf80005167b42e5a07c71ea2feaf235.png
[https_github.com_dcodeIO_ByteBuffer.js_wiki_API]: https://github.com/dcodeIO/ByteBuffer.js/wiki/API
[Message API]: https://htmlpreview.github.io/?https://raw.githubusercontent.com/dcodeIO/ProtoBuf.js/master/docs/ProtoBuf.Builder.Message.html
[Long.js]: https://github.com/dcodeIO/Long.js
[bignumber.js]: https://github.com/MikeMcl/bignumber.js
[Long.js API]: https://github.com/dcodeIO/Long.js#api
[http_www.ibm.com_developerworks_cn_linux_l-cn-gpb]: http://www.ibm.com/developerworks/cn/linux/l-cn-gpb/
[http_www.cnblogs.com_royenhome_archive_2010_10_29_1864860.html]: http://www.cnblogs.com/royenhome/archive/2010/10/29/1864860.html
[http_www.maxzhang.com_2015_09_ProtoBuf-js]: http://www.maxzhang.com/2015/09/ProtoBuf-js%E4%BD%BF%E7%94%A8%E6%8A%80%E5%B7%A7/