Rust序列化库musli的使用，musli提供高效灵活的数据序列化与反序列化功能

musli是一个灵活、快速且通用的Rust二进制序列化框架，性能优异且不妥协！它提供了一系列格式，每种格式都有其文档完善的功能和权衡。

概述

• 使用derives模块学习如何实现Encode和Decode特性
• 查看data_model了解Müsli的抽象数据模型
• 查看基准测试和大小比较了解框架性能
• 无缝兼容serde，可通过musli::serde模块实现

使用

在Cargo.toml中添加以下内容（根据你选择的格式）：

[dependencies]
musli = { version = "0.0.131", features = ["storage"] }

设计

核心功能由Encode和Decode派生宏实现，这些宏在derives模块中有详细文档。

use musli::{Encode, Decode};

#[derive(Encode, Decode)]
struct Person {
    /* .. fields .. */
}

注意：默认情况下字段由其数字索引标识，如果字段重新排序会改变。可以通过配置derives来重命名字段和设置默认命名策略。

完整示例

以下是一个完整的musli使用示例，展示如何序列化和反序列化数据：

use musli::{Encode, Decode};
use musli::storage::Encoding;

#[derive(Debug, Encode, Decode)]
struct Person {
    name: String,
    age: u32,
    #[musli(default)]
    address: Option<String>,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建编码实例
    let encoding = Encoding::new();
    
    // 创建示例数据
    let person = Person {
        name: "Alice".to_string(),
        age: 30,
        address: Some("123 Main St".to_string()),
    };
    
    // 序列化
    let bytes = encoding.to_vec(&person)?;
    println!("Serialized: {:?}", bytes);
    
    // 反序列化
    let decoded: Person = encoding.from_slice(&bytes)?;
    println!("Deserialized: {:?}", decoded);
    
    Ok(())
}

升级稳定性

musli支持不同级别的升级稳定性。以下示例展示完全升级稳定性：

use musli::{Encode, Decode};

#[derive(Debug, PartialEq, Encode, Decode)]
struct Version1 {
    #[musli(Binary, name = 0)]
    name: String,
}

#[derive(Debug, PartialEq, Encode, Decode)]
struct Version2 {
    #[musli(Binary, name = 0)]
    name: String,
    #[musli(Binary, name = 1)]
    #[musli(default)]
    age: Option<u32>,
}

let version2 = musli::wire::to_vec(&Version2 {
    name: String::from("Aristotle"),
    age: Some(61),
})?;

let version1: Version1 = musli::wire::decode(version2.as_slice())?;

模式

在musli中，同一个模型可以通过不同的模式进行序列化：

use musli::{Decode, Encode};
use musli::json::Encoding;

enum Alt {}

#[derive(Decode, Encode)]
#[musli(Text, name_all = "name")]
#[musli(mode = Alt, packed)]
struct Word<'a> {
    text: &'a str,
    teineigo: bool,
}

const TEXT: Encoding = Encoding::new();
const ALT: Encoding<Alt> = Encoding::new().with_mode();

let word = Word {
    text: "あります",
    teineigo: true,
};

let out = TEXT.to_string(&word)?;
assert_eq!(out, r#"{"text":"あります","teineigo":true}"#);

let out = ALT.to_string(&word)?;
assert_eq!(out, r#"["あります",true]"#);

性能优化

为了实现最高性能，可以使用以下优化方法：

use musli::alloc::{Allocator, System};
use musli::context::{self, ErrorMarker as Error};
use musli::options::{self, Float, Integer, Width, Options};
use musli::storage::Encoding;
use musli::{Decode, Encode};
use musli::alloc::Slice;

enum Packed {}

const OPTIONS: Options = options::new().fixed().native_byte_order().build();
const ENCODING: Encoding<OPTIONS, Packed> = Encoding::new().with_options().with_mode();

#[inline]
pub fn encode<'buf, T, A>(buf: &'buf mut [u8], value: &T, alloc: A) -> Result<&'buf [u8], Error>
where
    T: Encode<Packed>,
    A: Allocator,
{
    let cx = context::new_in(alloc);
    let w = ENCODING.to_slice_with(&cx, &mut buf[..], value)?;
    Ok(&buf[..w])
}

#[inline]
pub fn decode<'buf, T, A](buf: &'buf [u8], alloc: A) -> Result<T, Error>
where
    T: Decode<'buf, Packed, A>,
    A: Allocator,
{
    let cx = context::new_in(alloc);
    ENCODING.from_slice_with(&cx, buf)
}

与serde的区别

• Müsli的数据模型不与Rust绑定
• 使用GATs提供更易用的抽象
• 所有东西都是Decoder或Encoder
• 只在需要时使用访问者模式
• 发明了模式编码
• 完全支持no-std和no-alloc
• 提供详细的解码跟踪

格式

musli提供的格式及其能力：

完整示例demo

以下是一个更完整的musli使用示例，展示如何配置和使用不同的序列化模式：

use musli::{Encode, Decode};
use musli::json::Encoding;
use serde::{Serialize, Deserialize};

// 定义一个支持多种序列化模式的结构体
#[derive(Debug, PartialEq, Encode, Decode, Serialize, Deserialize)]
#[musli(name_all = "kebab-case")]
struct User {
    id: u64,
    username: String,
    #[musli(default)]
    #[serde(default)]
    email: Option<String>,
    is_active: bool,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建JSON编码实例
    let json_encoding = Encoding::new();
    
    // 创建用户数据
    let user = User {
        id: 42,
        username: "john_doe".to_string(),
        email: Some("john@example.com".to_string()),
        is_active: true,
    };
    
    // 序列化为JSON
    let json = json_encoding.to_string(&user)?;
    println!("Serialized JSON: {}", json);
    
    // 从JSON反序列化
    let decoded: User = json_encoding.from_str(&json)?;
    println!("Deserialized: {:?}", decoded);
    
    // 测试与serde的兼容性
    let serde_json = serde_json::to_string(&user)?;
    println!("Serde JSON: {}", serde_json);
    
    let musli_from_serde: User = json_encoding.from_str(&serde_json)?;
    println!("Musli from serde: {:?}", musli_from_serde);
    
    Ok(())
}

这个示例展示了：

1. 使用musli进行JSON序列化和反序列化
2. 结构体字段的默认值处理
3. 字段命名策略配置
4. 与serde的互操作性
5. 完整的错误处理

musli是一个强大的序列化框架，提供了丰富的功能和灵活的配置选项，能够满足各种序列化需求。