serde-generate

这个crate旨在将Rust中通过 serde-reflection 提取的数据格式编译成其他编程语言的类型定义和（反）序列化方法。

它可以作为一个库或命令行工具使用（见下文的 serdegen）。

支持的语言

以下编程语言完全支持作为目标语言

• C++ 17
• Java 8
• Python 3（需要numpy >= 1.20.1）
• Rust 2018
• Go >= 1.14
• C#（NetCoreApp >= 2.1）
• Swift 5.3

以下语言部分支持，仍在开发中

• TypeScript 4（与Deno打包并测试） (后续问题)
• Dart >= 2 (后续问题)

支持编码

目标语言中的类型定义旨在与提供特定 Serde编码格式的（反）序列化的运行时库一起使用。

此crate为以下二进制格式提供易于部署的运行时库，所有支持的语言

• Bincode（默认配置仅限），
• BCS（二进制规范序列化的缩写，是Diem区块链中使用的格式）。

使用Python和Bincode快速入门

在以下示例中，我们使用bincode将Rust中的Test值传输到Python。

use serde::{Deserialize, Serialize};
use serde_reflection::{Registry, Tracer, TracerConfig};
use std::io::Write;

#[derive(Serialize, Deserialize)]
struct Test {
    a: Vec<u64>,
    b: (u32, u32),
}

// Obtain the Serde format of `Test`. (In practice, formats are more likely read from a file.)
let mut tracer = Tracer::new(TracerConfig::default());
tracer.trace_simple_type::<Test>().unwrap();
let registry = tracer.registry().unwrap();

// Create Python class definitions.
let mut source = Vec::new();
let config = serde_generate::CodeGeneratorConfig::new("testing".to_string())
    .with_encodings(vec![serde_generate::Encoding::Bincode]);
let generator = serde_generate::python3::CodeGenerator::new(&config);
generator.output(&mut source, &registry)?;

assert!(
    String::from_utf8_lossy(&source).contains(
    r#"
@dataclass(frozen=True)
class Test:
    a: typing.Sequence[st.uint64]
    b: typing.Tuple[st.uint32, st.uint32]
"#));

// Append some test code to demonstrate Bincode deserialization
// using the runtime in `serde_generate/runtime/python/bincode`.
writeln!(
    source,
    r#"
value = Test.bincode_deserialize(bytes({:?}))
assert value == Test(a=[4, 6], b=(3, 5))
"#,
    bincode::serialize(&Test { a: vec![4, 6], b: (3, 5) }).unwrap(),
)?;

// Execute the Python code.
let mut child = std::process::Command::new("python3")
    .arg("-")
    .env("PYTHONPATH", std::env::var("PYTHONPATH").unwrap_or_default() + ":runtime/python")
    .stdin(std::process::Stdio::piped())
    .spawn()?;
child.stdin.as_mut().unwrap().write_all(&source)?;
let output = child.wait_with_output()?;
assert!(output.status.success());

二进制工具

除了Rust库外，此crate还提供了一个二进制工具 serdegen，用于处理磁盘上保存的Serde格式。

工具 serdegen 假设一个类型为 serde_reflection::Registry 的Rust值已被序列化到一个YAML文件中。生成此类值的推荐方法是使用库 serde-reflection 来检查Rust定义（也可参见上面的示例）。

为了快速测试，可以创建一个测试文件，如下所示

cat >test.yaml <<EOF
---
Foo:
  ENUM:
    0:
      A:
        NEWTYPE:
          U64
    1:
      B: UNIT
EOF

然后，以下命令将生成 Python 类定义并将它们写入 test.py

cargo run -p serde-generate -- --language python3 test.yaml > test.py

为了创建一个名为 test 的 Python 模块，并将 bincode 运行时安装在目录 $DEST 中，您可以运行

cargo run -p serde-generate -- --language python3 --with-runtimes serde bincode --module-name test --target-source-dir "$DEST" test.yaml

使用 --help 查看工具的帮助信息以获取更多选项。

注意：在此存储库之外，您可以使用 cargo install serde-generate 安装工具，然后使用 $HOME/.cargo/bin/serdegen。

贡献

请参阅 CONTRIBUTING 文件以了解如何提供帮助。

许可证

此项目可根据 Apache 2.0 许可证或 MIT 许可证 的条款使用。