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

jam-codec-derive是一个高效的Rust序列化与反序列化库，专门为自定义数据结构提供编解码功能。它通过过程宏简化了序列化/反序列化的实现过程。

特点

• 高性能二进制编码
• 零拷贝反序列化支持
• 紧凑的二进制格式
• 易于使用的派生宏

使用方法

1. 添加依赖

首先在Cargo.toml中添加依赖：

[dependencies]
jam-codec-derive = "0.1"
jam-codec = "0.1"

2. 基本使用

为结构体或枚举派生JamEncode和JamDecode特质：

use jam_codec_derive::{JamEncode, JamDecode};

#[derive(JamEncode, JamDecode, Debug, PartialEq)]
struct Person {
    id: u32,
    name: String,
    age: u8,
    is_active: bool,
}

3. 序列化和反序列化

use jam_codec::{JamEncode, JamDecode};

fn main() {
    let person = Person {
        id: 1,
        name: "Alice".to_string(),
        age: 30,
        is_active: true,
    };

    // 序列化
    let encoded = person.jam_encode();
    
    // 反序列化
    let decoded = Person::jam_decode(&encoded).unwrap();
    
    assert_eq!(person, decoded);
}

4. 高级特性

跳过字段

#[derive(JamEncode, JamDecode)]
struct Config {
    name: String,
    #[jam_codec(skip)]
    temp_value: u32, // 这个字段不会被编码/解码
}

自定义编码

#[derive(JamEncode, JamDecode)]
struct CustomData {
    #[jam_codec(with = "encode_ip", decode_with = "decode_ip")]
    ip_address: std::net::Ipv4Addr,
}

fn encode_ip(ip: &std::net::Ipv4Addr, writer: &mut impl std::io::Write) -> jam_codec::Result<()> {
    writer.write_all(&ip.octets())?;
    Ok(())
}

fn decode_ip(reader: &mut impl std::io::Read) -> jam_codec::Result<std::net::Ipv4Addr> {
    let mut buf = [0u8; 4];
    reader.read_exact(&mut buf)?;
    Ok(std::net::Ipv4Addr::from(buf))
}

5. 枚举支持

#[derive(JamEncode, JamDecode, Debug, PartialEq)]
enum Message {
    Text(String),
    Binary(Vec<u8>),
    Quit,
}

let msg = Message::Text("Hello".to_string());
let encoded = msg.jam_encode();
let decoded = Message::jam_decode(&encoded).unwrap();

性能建议

1. 对于大型结构，考虑使用Box或引用计数类型来减少复制
2. 尽可能使用固定大小的数组而不是Vec，如果大小是固定的
3. 对于频繁序列化的类型，实现JamEncode和JamDecode手动优化性能

错误处理

所有编解码操作都返回jam_codec::Result，可以处理各种IO和格式错误：

match Person::jam_decode(&invalid_data) {
    Ok(person) => println!("Decoded: {:?}", person),
    Err(e) => eprintln!("Decode error: {}", e),
}

完整示例代码

// 引入必要的trait和宏
use jam_codec::{JamEncode, JamDecode};
use jam_codec_derive::{JamEncode, JamDecode};
use std::net::Ipv4Addr;

// 基本结构体示例
#[derive(JamEncode, JamDecode, Debug, PartialEq)]
struct Person {
    id: u32,
    name: String,
    age: u8,
    is_active: bool,
}

// 跳过字段示例
#[derive(JamEncode, JamDecode, Debug, PartialEq)]
struct Config {
    name: String,
    #[jam_codec(skip)]
    temp_value: u32, // 这个字段不会被编码/解码
}

// 自定义编码示例
#[derive(JamEncode, JamDecode, Debug, PartialEq)]
struct CustomData {
    #[jam_codec(with = "encode_ip", decode_with = "decode_ip")]
    ip_address: Ipv4Addr,
}

fn encode_ip(ip: &Ipv4Addr, writer: &mut impl std::io::Write) -> jam_codec::Result<()> {
    writer.write_all(&ip.octets())?;
    Ok(())
}

fn decode_ip(reader: &mut impl std::io::Read) -> jam_codec::Result<Ipv4Addr> {
    let mut buf = [0u8; 4];
    reader.read_exact(&mut buf)?;
    Ok(Ipv4Addr::from(buf))
}

// 枚举示例
#[derive(JamEncode, JamDecode, Debug, PartialEq)]
enum Message {
    Text(String),
    Binary(Vec<u8>),
    Quit,
}

fn main() {
    // 基本结构体使用示例
    let person = Person {
        id: 1,
        name: "Alice".to_string(),
        age: 30,
        is_active: true,
    };
    
    let encoded_person = person.jam_encode();
    let decoded_person = Person::jam_decode(&encoded_person).unwrap();
    assert_eq!(person, decoded_person);

    // 跳过字段示例
    let config = Config {
        name: "test".to_string(),
        temp_value: 42,
    };
    
    let encoded_config = config.jam_encode();
    let decoded_config = Config::jam_decode(&encoded_config).unwrap();
    assert_eq!(config.name, decoded_config.name);
    assert_eq!(0, decoded_config.temp_value); // 跳过字段会被初始化为默认值

    // 自定义编码示例
    let custom_data = CustomData {
        ip_address: Ipv4Addr::new(127, 0, 0, 1),
    };
    
    let encoded_custom = custom_data.jam_encode();
    let decoded_custom = CustomData::jam_decode(&encoded_custom).unwrap();
    assert_eq!(custom_data.ip_address, decoded_custom.ip_address);

    // 枚举示例
    let msg = Message::Text("Hello".to_string());
    let encoded_msg = msg.jam_encode();
    let decoded_msg = Message::jam_decode(&encoded_msg).unwrap();
    assert_eq!(msg, decoded_msg);

    // 错误处理示例
    let invalid_data = vec![0u8; 10];
    match Person::jam_decode(&invalid_data) {
        Ok(p) => println!("Decoded person: {:?}", p),
        Err(e) => println!("Decode failed: {}", e),
    }
}