Rust序列化与反序列化库nanoserde-derive使用指南

概述

nanoserde-derive是一个轻量级、零依赖的Rust序列化与反序列化库，通过编译时derive宏提供高效的二进制和JSON格式支持。

主要特性

• 零运行时依赖
• 编译时derive宏实现
• 支持二进制和JSON格式
• 轻量级设计，编译速度快

使用方法

1. 添加依赖

在Cargo.toml中添加：

[dependencies]
nanoserde = "0.1"

2. 基本使用示例

use nanoserde::{DeBin, SerBin, DeJson, SerJson};

#[derive(DeBin, SerBin, DeJson, SerJson)]
struct User {
    id: u32,
    name: String,
    active: bool,
}

fn main() {
    // 序列化示例
    let user = User {
        id: 1,
        name: "Alice".to_string(),
        active: true,
    };
    
    // 二进制序列化
    let bin_data: Vec<u8> = SerBin::serialize_bin(&user);
    println!("Binary serialized: {:?}", bin_data);
    
    // JSON序列化
    let json_data = SerJson::serialize_json(&user);
    println!("JSON serialized: {}", json_data);
    
    // 反序列化示例
    let user_from_bin: User = DeBin::deserialize_bin(&bin_data).unwrap();
    let user_from_json: User = DeJson::deserialize_json(&json_data).unwrap();
    
    println!("Deserialized user name: {}", user_from_bin.name);
}

3. 支持的数据类型

• 基本类型：bool, i8, i16, i32, i64, u8, u16, u32, u64, f32, f64
• String和&str
• Vec<T>和数组
• Option<T>
• 元组（最多16个元素）
• 自定义结构体和枚举

4. 枚举类型支持

#[derive(DeBin, SerBin, DeJson, SerJson)]
enum Message {
    Text(String),
    Number(i32),
    Quit,
}

fn enum_example() {
    let msg = Message::Text("Hello".to_string());
    let bin_data = SerBin::serialize_bin(&msg);
    let deserialized: Message = DeBin::deserialize_bin(&bin_data).unwrap();
}

5. 自定义字段名（JSON序列化）

#[derive(DeJson, SerJson)]
struct Person {
    #[n(rename = "firstName")]
    first_name: String,
    #[n(rename = "lastName")]
    last_name: String,
}

注意事项

1. 确保所有字段类型都实现了相应的trait
2. 二进制格式不保证跨平台兼容性
3. 对于复杂嵌套结构，建议使用更成熟的序列化库如serde
4. 主要用于简单的数据结构和内部通信场景

性能建议

• 对于性能敏感的场景，优先使用二进制格式
• 避免在热路径中频繁创建临时序列化对象
• 考虑使用&str代替String以减少内存分配

这个库特别适合需要轻量级序列化解决方案且不希望引入额外依赖的项目。

完整示例demo

// 导入必要的trait
use nanoserde::{DeBin, SerBin, DeJson, SerJson};

// 定义用户结构体，实现所有序列化trait
#[derive(Debug, DeBin, SerBin, DeJson, SerJson)]
struct User {
    id: u32,
    name: String,
    active: bool,
    tags: Vec<String>,
}

// 定义消息枚举，支持多种消息类型
#[derive(Debug, DeBin, SerBin, DeJson, SerJson)]
enum Message {
    Text(String),
    Number(i32),
    UserData(User),
    Quit,
}

// 定义人员结构体，支持JSON字段重命名
#[derive(Debug, DeJson, SerJson)]
struct Person {
    #[n(rename = "firstName")]
    first_name: String,
    #[n(rename = "lastName")]
    last_name: String,
    age: u8,
}

fn main() {
    println!("=== nanoserde-derive 完整示例 ===");
    
    // 示例1: 基本结构体序列化
    println!("\n1. 基本结构体序列化示例:");
    let user = User {
        id: 42,
        name: "Bob".to_string(),
        active: true,
        tags: vec!["rust".to_string(), "developer".to_string()],
    };
    
    // 二进制序列化与反序列化
    let bin_data: Vec<u8> = SerBin::serialize_bin(&user);
    println!("二进制数据长度: {} bytes", bin_data.len());
    
    let user_from_bin: User = DeBin::deserialize_bin(&bin_data).unwrap();
    println!("从二进制反序列化: {:?}", user_from_bin);
    
    // JSON序列化与反序列化
    let json_data = SerJson::serialize_json(&user);
    println!("JSON数据: {}", json_data);
    
    let user_from_json: User = DeJson::deserialize_json(&json_data).unwrap();
    println!("从JSON反序列化: {:?}", user_from_json);
    
    // 示例2: 枚举类型序列化
    println!("\n2. 枚举类型序列化示例:");
    let messages = vec![
        Message::Text("Hello World".to_string()),
        Message::Number(100),
        Message::UserData(user),
        Message::Quit,
    ];
    
    for msg in messages {
        let json_msg = SerJson::serialize_json(&msg);
        println!("枚举JSON: {}", json_msg);
        
        let bin_msg: Vec<u8> = SerBin::serialize_bin(&msg);
        println!("枚举二进制长度: {} bytes", bin_msg.len());
    }
    
    // 示例3: 字段重命名示例
    println!("\n3. JSON字段重命名示例:");
    let person = Person {
        first_name: "张".to_string(),
        last_name: "三".to_string(),
        age: 30,
    };
    
    let person_json = SerJson::serialize_json(&person);
    println!("重命名字段JSON: {}", person_json);
    
    // 验证反序列化
    let person_from_json: Person = DeJson::deserialize_json(&person_json).unwrap();
    println!("反序列化人员: {:?}", person_from_json);
    
    println!("\n=== 示例执行完成 ===");
}

// 单元测试示例
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_basic_serialization() {
        let user = User {
            id: 1,
            name: "Test".to_string(),
            active: false,
            tags: vec![],
        };
        
        // 测试二进制往返
        let bin_data = SerBin::serialize_bin(&user);
        let decoded: User = DeBin::deserialize_bin(&bin_data).unwrap();
        assert_eq!(user.id, decoded.id);
        assert_eq!(user.name, decoded.name);
        
        // 测试JSON往返
        let json_data = SerJson::serialize_json(&user);
        let decoded_json: User = DeJson::deserialize_json(&json_data).unwrap();
        assert_eq!(user.active, decoded_json.active);
    }
    
    #[test]
    fn test_enum_serialization() {
        let msg = Message::Text("test".to_string());
        let bin_data = SerBin::serialize_bin(&msg);
        let decoded: Message = DeBin::deserialize_bin(&bin_data).unwrap();
        
        if let Message::Text(text) = decoded {
            assert_eq!(text, "test");
        } else {
            panic!("枚举反序列化失败");
        }
    }
}

这个完整示例展示了nanoserde-derive库的主要功能，包括：

• 基本结构体的二进制和JSON序列化
• 枚举类型的序列化支持
• JSON字段重命名功能
• 完整的往返序列化测试
• 单元测试示例

要运行此示例，请确保在Cargo.toml中添加了正确的依赖项，然后使用cargo run命令执行。