MessagePack-CSharp 从 v1.x 迁移到 v2.x 的完整指南

MessagePack-CSharp 从 v1.x 迁移到 v2.x 的完整指南

MessagePack-CSharp Extremely Fast MessagePack Serializer for C#(.NET, .NET Core, Unity, Xamarin). / msgpack.org[C#] 项目地址: https://gitcode.com/gh_mirrors/me/MessagePack-CSharp

前言

MessagePack-CSharp 是一个高效的二进制序列化库，v2.x 版本带来了许多重要的架构改进和性能优化。本文将全面解析从 v1.x 迁移到 v2.x 的关键变化，帮助开发者顺利完成版本升级。

核心变化概述

v2.x 版本的主要改进包括：

1. 引入了全新的 MessagePackSerializerOptions 类作为核心配置容器
2. 优化了序列化/反序列化 API，支持更灵活的内存操作
3. 重构了内部架构，提升了大型数据处理的性能
4. 移除了部分过时的 API 和功能

配置系统的重大变更

MessagePackSerializerOptions 类

v2.x 将配置集中到不可变的 MessagePackSerializerOptions 类中，取代了 v1.x 中分散的配置方式。

// v1.x 方式
var data = MessagePackSerializer.Serialize(obj, StandardResolverAllowPrivate.Instance);

// v2.x 推荐方式
var options = StandardResolverAllowPrivate.Options;
var data = MessagePackSerializer.Serialize(obj, options);

配置修改采用"克隆并修改"模式：

var options = StandardResolver.Options
    .WithCompression(MessagePackCompression.Lz4BlockArray)
    .WithResolver(MyCustomResolver.Instance);

序列化 API 的改进

序列化接口变化

v2.x 使用 IBufferWriter<byte> 替代了直接操作字节数组的方式：

// v1.x
int Serialize(ref byte[] bytes, int offset, T value, IFormatterResolver formatterResolver);

// v2.x
void Serialize(ref MessagePackWriter writer, T value, MessagePackSerializerOptions options);

反序列化增强

支持更多数据源类型：

• ReadOnlyMemory<byte>
• ReadOnlySequence<byte>
• 原生支持异步流处理

// 流处理示例
using var streamReader = new MessagePackStreamReader(stream);
while (await streamReader.ReadAsync() is ReadOnlySequence<byte> msgpack)
{
    var item = MessagePackSerializer.Deserialize<T>(msgpack);
}

异常处理改进

v2.x 统一了异常类型，所有序列化异常都会包装为 MessagePackSerializationException：

try
{
    var obj = MessagePackSerializer.Deserialize<T>(data);
}
catch (MessagePackSerializationException ex)
{
    // 统一处理序列化异常
}

内置组件变更

移除的解析器

| v1.x 解析器 | v2.x 替代方案 | |---------------------|--------------------------| | UnsafeBinaryResolver | NativeDecimal/NativeGuid |

组合解析器改进

CompositeResolver 不再使用静态属性，可以安全地多次使用：

var resolver = CompositeResolver.Create(
    new[] { MyFormatter.Instance },
    new[] { StandardResolver.Instance }
);

自定义格式化器迁移指南

自定义格式化器接口有重大变化：

// v1.x 接口
public interface IMessagePackFormatter<T>
{
    int Serialize(ref byte[] bytes, int offset, T value, IFormatterResolver formatterResolver);
    T Deserialize(byte[] bytes, int offset, IFormatterResolver formatterResolver, out int readSize);
}

// v2.x 接口
public interface IMessagePackFormatter<T>
{
    void Serialize(ref MessagePackWriter writer, T value, MessagePackSerializerOptions options);
    T Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options);
}

格式化器迁移示例

// v1.x 格式化器
class Int16Formatter : IMessagePackFormatter<short>
{
    public int Serialize(ref byte[] bytes, int offset, short value, IFormatterResolver resolver)
    {
        return MessagePackBinary.WriteInt16(ref bytes, offset, value);
    }
    
    public short Deserialize(byte[] bytes, int offset, IFormatterResolver resolver, out int readSize)
    {
        return MessagePackBinary.ReadInt16(bytes, offset, out readSize);
    }
}

// v2.x 格式化器
class Int16Formatter : IMessagePackFormatter<short>
{
    public void Serialize(ref MessagePackWriter writer, short value, MessagePackSerializerOptions options)
    {
        writer.Write(value);
    }
    
    public short Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options)
    {
        return reader.ReadInt16();
    }
}

LZ4 压缩的变更

v1.x 的专用 LZ4MessagePackSerializer 已被移除，改用配置方式：

// v1.x
var data = LZ4MessagePackSerializer.Serialize(obj);

// v2.x
var options = MessagePackSerializerOptions.Standard.WithCompression(MessagePackCompression.Lz4Block);
var data = MessagePackSerializer.Serialize(obj, options);

类型处理变化

TypelessFormatter 改进

BindToType 静态属性被移除，改为通过重写 MessagePackSerializerOptions 的方法实现：

class CustomOptions : MessagePackSerializerOptions
{
    public override Type LoadType(string typeName)
    {
        // 自定义类型加载逻辑
    }
}

性能优化建议

1. 对于大型数据，使用 ReadOnlySequence<byte> 避免内存拷贝
2. 重用 MessagePackSerializerOptions 实例减少配置开销
3. 流处理时优先使用 MessagePackStreamReader
4. 避免频繁修改静态默认配置

总结

MessagePack-CSharp v2.x 通过架构重构带来了显著的性能提升和使用体验改进。迁移过程虽然需要一定的代码修改，但新的 API 设计更加合理和高效。建议开发者在充分测试的基础上逐步完成迁移，特别要注意自定义格式化器和特殊配置的适配工作。

MessagePack-CSharp Extremely Fast MessagePack Serializer for C#(.NET, .NET Core, Unity, Xamarin). / msgpack.org[C#] 项目地址: https://gitcode.com/gh_mirrors/me/MessagePack-CSharp