npsd (网络有效载荷序列化/反序列化)

npsd crate提供了一种灵活高效的方式来序列化和反序列化网络有效载荷。它支持将Rust类型转换为适合网络传输的字节流，并从网络接收的字节流中重建这些类型。这对于需要高效可靠数据交换的网络应用特别有用。

功能

• 将复杂的Rust类型序列化和反序列化为字节流。
• 支持自定义序列化上下文。
• 支持序列化和反序列化过程中的可扩展处理中间件。

npsd与serde之间的区别

• 目的: npsd专门设计用于网络有效载荷的序列化和反序列化，提供对网络传输的字节流的高效处理。另一方面，serde是一个通用的序列化框架，支持多种格式（JSON、XML等）。

• 自定义上下文: npsd支持自定义序列化上下文和中间件，以支持序列化和反序列化过程中的可扩展处理，这适用于网络应用。而serde专注于无格式化的序列化。

• 过程宏: 两个库都提供了过程宏，但npsd包含特定的宏（Schema、Bitmap、AsyncSchema、AsyncBitmap、Info）用于与网络相关的序列化场景。

过程宏

npsd crate还提供过程宏来生成序列化和反序列化实现。

Schema

Schema宏为序列化和反序列化复杂的Rust类型生成实现。

示例

use npsd::{Payload, Schema, Next, Middleware};

#[derive(Schema, PartialEq, Debug)]
enum Animal {
    Dog,
    Frog(String, Vec<isize>),
    Cat { age: usize, name: String },
    AntHive(Vec<String>),
}

#[test]
fn test_schema() {
    // Create Middleware
    let mut next = Next::default();

    // Create an instance of `Animal`.
    let animal = Animal::Frog("Frog".to_string(), vec![12393818, -19383812, 11111, -1093838482]);

    // Serialize the `animal` instance into a packet.
    animal.into_packet(&mut (), &mut next).unwrap();

    // Create copy of serialized data if needed
    let _serialized = next.serialized();

    // Deserialize the packet back into an `Animal` instance.
    let deserialized = Animal::from_packet(&mut (), &mut next).unwrap();

    // Ensure the deserialized instance matches the original.
    assert_eq!(deserialized, animal);
}

Bitmap

Bitmap宏为序列化和反序列化位图生成实现。

示例

use npsd::{Payload, Bitmap, Next, Middleware};

#[derive(Bitmap, PartialEq, Debug)]
struct Flags {
    a: bool,
    b: bool,
    c: bool,
}

#[test]
fn test_bitmap() {
    // Create Middleware
    let mut next = Next::default();

    // Create an u8 bitmap of `Flags`.
    let flags = Flags { a: true, b: false, c: true };

    // Serialize the `Flags` into a packet.
    flags.into_packet(&mut (), &mut next).unwrap();

    // Create copy of serialized data if needed
    let _serialized = next.serialized();

    // Deserialize the packet back into an `Flags`.
    let deserialized = Flags::from_packet(&mut (), &mut next).unwrap();

    // Ensure the deserialized matches the original.
    assert_eq!(deserialized, flags);
}

AsyncSchema

AsyncSchema宏为异步序列化和反序列化复杂的Rust类型生成实现。

示例

use npsd::{AsyncPayload, AsyncSchema, Next, Info};

#[derive(AsyncSchema, Info, PartialEq, Debug)]
enum Animal {
    Dog,
    Frog(String, Vec<isize>),
    Cat { age: usize, name: String },
    AntHive(Vec<String>),
}

#[tokio::test]
async fn test_schema() {
    // Create Middleware
    let mut next = Next::default();

    // Create an instance of `Animal`.
    let animal = Animal::Frog("Frog".to_string(), vec![12393818, -19383812, 11111, -1093838482]);

    // Serialize the `animal` instance into a packet.
    animal.poll_into_packet(&mut (), &mut next).await.unwrap();

    // Create copy of serialized data if needed
    let _serialized = next.serialized();

    // Deserialize the packet back into an `Animal` instance.
    let deserialized = Animal::poll_from_packet(&mut (), &mut next).await.unwrap();

    // Ensure the deserialized instance matches the original.
    assert_eq!(deserialized, animal);
}

AsyncBitmap

AsyncBitmap宏为异步序列化和反序列化位图生成实现。

示例

use npsd::{AsyncPayload, AsyncBitmap, Next, Info};

#[derive(AsyncBitmap, PartialEq, Debug)]
struct Flags {
    a: bool,
    b: bool,
    c: bool,
}

#[test]
fn test_bitmap() {
    // Create Middleware
    let mut next = Next::default();

    // Create an u8 bitmap of `Flags`.
    let flags = Flags { a: true, b: false, c: true };

    // Serialize the `Flags` into a packet.
    flags.poll_into_packet(&mut (), &mut next).await.unwrap();

    // Create copy of serialized data if needed
    let _serialized = next.serialized();

    // Deserialize the packet back into an `Flags`.
    let deserialized = Flags::poll_from_packet(&mut (), &mut next).await.unwrap();

    // Ensure the deserialized matches the original.
    assert_eq!(deserialized, flags);
}

特质

PayloadContext

PayloadContext 特性提供了一种解包用于有效载荷处理中上下文的方法。

中间件

Middleware 特性定义了将类型转换为字节数据有效载荷以及从字节数据有效载荷转换为类型的方法。

AsyncMiddleware

AsyncMiddleware 特性定义了异步方法以将类型转换为字节数据有效载荷以及从字节数据有效载荷转换为类型。

IntoPayload

IntoPayload 特性用于将类型转换为字节数据有效载荷。

AsyncIntoPayload

AsyncIntoPayload 特性用于异步地将类型转换为字节数据有效载荷。

FromPayload

FromPayload 特性用于将字节数据有效载荷转换回类型。

AsyncFromPayload

AsyncFromPayload 特性用于异步地将字节数据有效载荷转换回类型。

有效载荷信息

PayloadInfo 特性提供了有关有效载荷的元数据。以下是相关常量和它们的描述：

• const HASH: u64：与类型关联的常量哈希值。此哈希值使用类型的字符串表示形式计算，并为有效载荷类型提供唯一的标识符。
• const TYPE: &'static str：表示有效载荷类型的字符串。这用于以可读格式识别有效载荷类型。
• const SIZE: Option<usize>：表示有效载荷大小的可选常量。如果适用，可以用于指定有效载荷的固定大小。

有效载荷

Payload 特性结合了 IntoPayload 和 FromPayload，以简化类型的完整序列化和反序列化。

AsyncPayload

AsyncPayload 特性结合了 AsyncIntoPayload 和 AsyncFromPayload，以提供异步方法的完整序列化和反序列化。

贡献

欢迎贡献！如果您遇到任何问题或对改进有建议，请随时提交拉取请求或打开问题。

许可证

本项目采用 Apache 2.0 许可证。