MessagePack Ruby 技术文档

1. 安装指南

使用 Bundler 安装

在 Gemfile 中添加以下内容：

gem 'msgpack'

然后运行以下命令安装：

bundle install

使用 RubyGems 安装

直接通过 RubyGems 安装：

gem install msgpack

从源码构建并安装

如果你已经克隆了 msgpack-ruby 仓库，可以通过以下步骤构建并安装：

bundle
rake
gem install --local pkg/msgpack

2. 项目的使用说明

MessagePack 是一种高效的二进制序列化格式，适用于多种语言之间的数据交换。它比 JSON 更快且更小。以下是一些常见的使用场景：

• 在 Rails 中使用 RABL 创建返回 MessagePack 格式的 REST API。
• 在 memcached 或 Redis 中存储通过 MessagePack 序列化的对象。
• 从移动设备（如智能手机）上传高效格式的数据。
• 设计与嵌入式设备通信的可移植协议。
• 在不同语言编写的软件组件之间交换对象。

3. 项目 API 使用文档

序列化对象

使用 MessagePack.pack 或 to_msgpack 方法：

require 'msgpack'
msg = MessagePack.pack(obj)  # 或者
msg = obj.to_msgpack
File.binwrite('mydata.msgpack', msg)

流式序列化

使用 Packer 进行流式序列化：

pk = MessagePack::Packer.new(io)
pk.write_array_header(2).write(e1).write(e2).flush

反序列化对象

使用 MessagePack.unpack 方法：

require 'msgpack'
msg = File.binread('mydata.msgpack')
obj = MessagePack.unpack(msg)

流式反序列化

使用 Unpacker 进行流式反序列化：

u = MessagePack::Unpacker.new(io)
u.each do |obj|
  # 处理对象
end

序列化和反序列化符号

默认情况下，符号会被序列化为字符串：

packed = :symbol.to_msgpack     # => "\xA6symbol"
MessagePack.unpack(packed)      # => "symbol"

可以通过注册扩展类型来定制符号的序列化：

MessagePack::DefaultFactory.register_type(0x00, Symbol)
packed = :symbol.to_msgpack     # => "\xc7\x06\x00symbol"
MessagePack.unpack(packed)      # => :symbol

序列化和反序列化时间实例

默认情况下，MessagePack 的时间戳扩展类型未启用。可以通过以下方式启用：

MessagePack::DefaultFactory.register_type(
  MessagePack::Timestamp::TYPE, # 或者直接使用 -1
  Time,
  packer: MessagePack::Time::Packer,
  unpacker: MessagePack::Time::Unpacker
)

扩展类型

Packer 和 Unpacker 支持 MessagePack 的扩展类型：

pk = MessagePack::Packer.new(io)
pk.register_type(0x01, MyClass1, :to_msgpack_ext)
pk.register_type(0x02, MyClass2) { |obj| obj.how_to_serialize() }

uk = MessagePack::Unpacker.new()
uk.register_type(0x01, MyClass1, :from_msgpack_ext)
uk.register_type(0x02) { |data| MyClass2.create_from_serialized_data(data) }

对象池

创建 Packer 和 Unpacker 对象是昂贵的操作。为了获得最佳性能，建议重用这些对象：

factory = MessagePack::Factory.new
factory.register_type(0x01, Point, packer: ->(point, packer) {
  packer.write(point.x)
  packer.write(point.y)
}, unpacker: ->(unpacker) {
  x = unpacker.read
  y = unpacker.read
  Point.new(x, y)
}, recursive: true)

pool = factory.pool(5)
pool.load(pool.dump(Point.new(12, 34))) # => #<struct Point x=12, y=34>

4. 项目安装方式

使用 Bundler 安装

在 Gemfile 中添加以下内容：

gem 'msgpack'

然后运行以下命令安装：

bundle install

使用 RubyGems 安装

直接通过 RubyGems 安装：

gem install msgpack

从源码构建并安装

如果你已经克隆了 msgpack-ruby 仓库，可以通过以下步骤构建并安装：

bundle
rake
gem install --local pkg/msgpack

总结

MessagePack 是一个高效的二进制序列化格式，适用于多种语言之间的数据交换。通过本文档，你可以了解如何安装、使用以及通过 API 进行序列化和反序列化操作。希望本文档能帮助你更好地理解和使用 MessagePack。