afastdata

English | 中文

高性能 Rust 二进制序列化/反序列化框架，通过 derive 宏为自定义类型自动生成序列化代码。

特性

零配置派生宏 — #[derive(AFastSerialize, AFastDeserialize)] 一行搞定
丰富的类型支持 — 基本类型、String、Vec<T>、Option<T>、[T; N]、嵌套结构体、枚举
泛型支持 — 自动为泛型参数添加 trait 约束
可配置长度前缀 — 默认 u32（最大 4GB），可通过 feature 切换为 u64
统一小端序 — 所有多字节数据使用 little-endian 编码
零外部依赖 — 运行时无第三方依赖

快速开始

安装

在 Cargo.toml 中添加依赖：

[dependencies]
afastdata = "0.0.1"

如需 u64 长度前缀：

[dependencies]
afastdata = { version = "0.0.1", features = ["len-u64"] }

基本用法

use afastdata::{AFastSerialize, AFastDeserialize};

#[derive(AFastSerialize, AFastDeserialize, Debug, PartialEq)]
struct User {
    name: String,
    age: u32,
    email: Option<String>,
}

fn main() {
    let user = User {
        name: String::from("Alice"),
        age: 30,
        email: Some(String::from("alice@example.com")),
    };

    // 序列化
    let bytes = user.to_bytes();

    // 反序列化
    let (decoded, consumed) = User::from_bytes(&bytes).unwrap();
    assert_eq!(user, decoded);
    println!("消耗 {} 字节", consumed);
}

枚举示例

use afastdata::{AFastSerialize, AFastDeserialize};

#[derive(AFastSerialize, AFastDeserialize, Debug, PartialEq)]
enum Command {
    Ping,
    Send { to: String, message: String },
    Broadcast(Vec<String>),
}

fn main() {
    let cmd = Command::Send {
        to: String::from("Bob"),
        message: String::from("Hello!"),
    };

    let bytes = cmd.to_bytes();
    let (decoded, _) = Command::from_bytes(&bytes).unwrap();
    assert_eq!(cmd, decoded);
}

泛型结构体

use afastdata::{AFastSerialize, AFastDeserialize};

#[derive(AFastSerialize, AFastDeserialize, Debug, PartialEq)]
struct Response<T> {
    code: u32,
    data: Option<T>,
    message: String,
}

fn main() {
    let resp = Response {
        code: 200,
        data: Some(vec![1i32, 2, 3]),
        message: String::from("ok"),
    };

    let bytes = resp.to_bytes();
    let (decoded, _) = Response::<Vec<i32>>::from_bytes(&bytes).unwrap();
    assert_eq!(resp, decoded);
}

支持的类型

类型	序列化方式	字节数
`i8`, `u8`	little-endian	1
`i16`, `u16`	little-endian	2
`i32`, `u32`	little-endian	4
`i64`, `u64`	little-endian	8
`i128`, `u128`	little-endian	16
`f32`	IEEE 754 little-endian	4
`f64`	IEEE 754 little-endian	8
`bool`	`0x00`=false, `0x01`=true	1
`String`	LenInt 长度前缀 + UTF-8 字节	变长
`&str`	LenInt 长度前缀 + UTF-8 字节（仅序列化）	变长
`Vec<T>`	LenInt 元素个数 + 逐元素编码	变长
`Option<T>`	1 字节标记 + 数据（仅 Some）	变长
`[T; N]`	逐元素编码，无长度前缀	固定
结构体	逐字段编码，无额外前缀	变长
枚举	u32 变体索引 + 变体字段数据	变长

编码格式详解

结构体

所有字段按声明顺序依次序列化，无额外前缀：

[field1 bytes][field2 bytes][field3 bytes]...

枚举

先写入 u32 变体索引（从 0 开始，按声明顺序递增），再写入变体字段数据：

[u32 variant_index][field1 bytes][field2 bytes]...

Unit 变体只写入索引，无字段数据。

长度前缀

String、Vec<T> 等变长类型使用 LenInt 作为长度前缀：

默认：u32 little-endian（4 字节，最大约 4GB）
启用 len-u64 feature 后：u64 little-endian（8 字节）

Feature Flags

Feature	说明
`len-u64`	将长度前缀从 `u32` 切换为 `u64`

项目结构

afastdata/
├── Cargo.toml              # Workspace 配置
├── README.md               # 中文文档（本文件）
├── README_EN.md            # English documentation
├── afastdata/              # 统一入口 crate
│   ├── Cargo.toml
│   ├── src/lib.rs          # Re-export 核心 trait 和 derive 宏
│   └── examples/
│       └── basic.rs        # 基础使用示例
├── afastdata-core/         # 核心库
│   ├── Cargo.toml          # 含 `len-u64` feature
│   └── src/lib.rs          # trait 定义 + 基本类型实现
└── afastdata-macro/        # Proc-macro 库
    ├── Cargo.toml
    └── src/lib.rs          # AFastSerialize / AFastDeserialize derive 宏

运行示例

cargo run --example basic -p afastdata

运行测试

cargo test --workspace

License

MIT

afastdata 0.0.1