Rust高效数据编解码库jam-codec的使用，支持高性能序列化与压缩传输

Parity JAM Codec

JAM Codec是SCALE二进制编解码器的Rust实现，具有增强的紧凑编码功能。SCALE是一种轻量级格式，适用于资源受限的执行环境，如区块链运行时和低功耗、低内存设备。

需要注意的是，编码上下文（了解类型和数据结构）需要在编码和解码两端分别知晓。编码数据不包含这些上下文信息。

实现

编解码器使用以下特性实现：

Encode

Encode trait用于将数据编码为SCALE格式：

• size_hint(&self) -> usize：获取编码数据所需的容量（字节）
• encode_to<T: Output>(&self, dest: &mut T)：将值编码并附加到目标缓冲区
• encode(&self) -> Vec<u8>：编码类型数据并返回切片
• using_encoded<R, F: FnOnce(&[u8]) -> R>(&self, f: F) -> R：编码类型数据并在编码值上执行闭包

Decode

Decode trait用于将编码数据反序列化/解码为相应类型：

• fn decode<I: Input>(value: &mut I) -> Result<Self, Error>：尝试从SCALE格式解码值

CompactAs

CompactAs trait用于将自定义类型/结构体包装为紧凑类型：

• encode_as(&self) -> &Self::As：将类型编码为紧凑类型
• decode_from(_: Self::As) -> Result<Self, Error>：从紧凑可编码类型解码

HasCompact

HasCompact trait表示对应类型是紧凑可编码类型。

EncodeLike

EncodeLike trait需要手动为每种类型实现。使用derive时自动完成。

使用示例

简单类型

# // 如果不使用derive特性，需要导入宏
# #[cfg(not(feature="derive"))]
# use jam_codec_derive::{Encode, Decode};

use jam_codec::{Encode, Decode};

#[derive(Debug, PartialEq, Encode, Decode)]
enum EnumType {
    #[codec(index = 15)]
    A,
    B(u32, u64),
    C {
        a: u32,
        b: u64,
    },
}

let a = EnumType::A;
let b = EnumType::B(1, 2);
let c = EnumType::C { a: 1, b: 2 };

a.using_encoded(|ref slice| {
    assert_eq!(slice, &b"\x0f");
});

b.using_encoded(|ref slice| {
    assert_eq!(slice, &b"\x01\x01\0\0\0\x02\0\0\0\0\0\0\0");
});

c.using_encoded(|ref slice| {
    assert_eq!(slice, &b"\x02\x01\0\0\0\x02\0\0\0\0\0\0\0");
});

let mut da: &[u8] = b"\x0f";
assert_eq!(EnumType::decode(&mut da).ok(), Some(a));

let mut db: &[u8] = b"\x01\x01\0\0\0\x02\0\0\0\0\0\0\0";
assert_eq!(EnumType::decode(&mut db).ok(), Some(b));

let mut dc: &[u8] = b"\x02\x01\0\0\0\x02\0\0\0\0\0\0\0";
assert_eq!(EnumType::decode(&mut dc).ok(), Some(c));

let mut dz: &[u8] = &[0];
assert_eq!(EnumType::decode(&mut dz).ok(), None);

# fn main() { }

带有HasCompact的紧凑类型

# // 如果不使用derive特性，需要导入宏
# #[cfg(not(feature="derive"))]
# use jam_codec_derive::{Encode, Decode};

use jam_codec::{Encode, Decode, Compact, HasCompact};

#[derive(Debug, PartialEq, Encode, Decode)]
struct Test1CompactHasCompact<T: HasCompact> {
    #[codec(compact)]
    bar: T,
}

#[derive(Debug, PartialEq, Encode, Decode)]
struct Test1HasCompact<T: HasCompact> {
    #[codec(encoded_as = "<T as HasCompact>::Type")]
    bar: T,
}

let test_val: (u64, usize) = (0u64, 1usize);

let encoded = Test1HasCompact { bar: test_val.0 }.encode();
assert_eq!(encoded.len(), test_val.1);
assert_eq!(<Test1CompactHasCompact<u64>>::decode(&mut &encoded[..]).unwrap().bar, test_val.0);

# fn main() { }

带有CompactAs的类型

# // 如果不使用derive特性，需要导入宏
# #[cfg(not(feature="derive"))]
# use jam_codec_derive::{Encode, Decode};

use serde_derive::{Serialize, Deserialize};
use jam_codec::{Encode, Decode, Compact, HasCompact, CompactAs, Error};

#[cfg_attr(feature = "std", derive(Serialize, Deserialize, Debug))]
#[derive(PartialEq, Eq, Clone)]
struct StructHasCompact(u32);

impl CompactAs for StructHasCompact {
    type As = u32;

    fn encode_as(&self) -> &Self::As {
        &12
    }

    fn decode_from(_: Self::As) -> Result<Self, Error> {
        Ok(StructHasCompact(12))
    }
}

impl From<Compact<StructHasCompact>> for StructHasCompact {
    fn from(_: Compact<StructHasCompact>) -> Self {
        StructHasCompact(12)
    }
}

#[derive(Debug, PartialEq, Encode, Decode)]
enum TestGenericHasCompact<T> {
    A {
        #[codec(compact)] a: T
    },
}

let a = TestGenericHasCompact::A::<StructHasCompact> {
    a: StructHasCompact(12325678),
};

let encoded = a.encode();
assert_eq!(encoded.len(), 2);

# fn main() { }

完整示例

下面是一个完整的jam-codec使用示例，展示如何进行高效的数据序列化和反序列化：

use jam_codec::{Encode, Decode};

#[derive(Debug, PartialEq, Encode, Decode)]
struct Person {
    name: String,
    age: u32,
    #[codec(compact)]
    salary: u64,  // 使用紧凑编码
    skills: Vec<String>,
}

fn main() {
    // 创建示例数据
    let person = Person {
        name: "Alice".to_string(),
        age: 30,
        salary: 100_000,  // 大数字将使用紧凑编码
        skills: vec!["Rust".to_string(), "Blockchain".to_string()],
    };

    // 序列化
    let encoded = person.encode();
    println!("Encoded data ({} bytes): {:?}", encoded.len(), encoded);

    // 反序列化
    let mut input = &encoded[..];
    let decoded = Person::decode(&mut input).unwrap();
    println!("Decoded: {:?}", decoded);

    assert_eq!(person, decoded);
}

安装

在项目目录中运行以下Cargo命令：

cargo add jam-codec

或者在Cargo.toml中添加：

jam-codec = "0.1.0"

许可证

Apache-2.0