为什么我们需要另一种序列化格式？Borsh 是第一个优先考虑以下对安全关键项目至关重要的特性的序列化器

• 一致的、明确的二进制表示
  • 一致性意味着对象和它们的二进制表示之间存在双射映射。没有两个二进制表示可以反序列化为同一个对象。这对于使用二进制表示来计算哈希的应用程序非常有用；
  • Borsh 随附一个完整的规范，可用于其他语言中的实现；
• 安全。Borsh 实现使用安全的编码实践。在 Rust 中，Borsh 几乎只使用安全代码，只有一个例外是使用 unsafe 以避免耗尽攻击；
• 速度。在 Rust 中，Borsh 通过放弃使用 Serde 而实现高性能，在某些情况下比 bincode 更快；这也减少了代码大小。

示例

use borsh::{BorshSerialize, BorshDeserialize};

#[derive(BorshSerialize, BorshDeserialize, PartialEq, Debug)]
struct A {
    x: u64,
    y: String,
}

#[test]
fn test_simple_struct() {
    let a = A {
        x: 3301,
        y: "liber primus".to_string(),
    };
    let encoded_a = a.try_to_vec().unwrap();
    let decoded_a = A::try_from_slice(&encoded_a).unwrap();
    assert_eq!(a, decoded_a);
}

功能

放弃使用 Serde 允许 borsh 拥有一些当前对于 serde 兼容序列化器不可用的功能。目前我们支持两个功能：borsh_init 和 borsh_skip（前者在 Serde 中不可用）。

borsh_init 允许在反序列化后自动运行初始化函数。这对于设计为严格不可变的对象非常有用。使用示例

#[derive(BorshSerialize, BorshDeserialize)]
#[borsh_init(init)]
struct Message {
    message: String,
    timestamp: u64,
    public_key: CryptoKey,
    signature: CryptoSignature
    hash: CryptoHash
}

impl Message {
    pub fn init(&mut self) {
        self.hash = CryptoHash::new().write_string(self.message).write_u64(self.timestamp);
        self.signature.verify(self.hash, self.public_key);
    }
}

borsh_skip 允许跳过序列化/反序列化字段，假设它们实现了 Default 特性，类似于 #[serde(skip)]。

#[derive(BorshSerialize, BorshDeserialize)]
struct A {
    x: u64,
    #[borsh_skip]
    y: f32,
}

基准测试

我们对区块链项目最关注的对象进行了以下基准测试：区块、区块头、交易、账户。我们从 nearprotocol 区块链中获取了对象结构。我们使用 Criterion 构建以下图表。

基准测试在 Google Cloud n1-standard-2 (2 vCPUs, 7.5 GB 内存) 上运行。

区块头序列化速度与区块头大小（以字节为单位）的对比（大小仅大致对应序列化复杂性，导致图形不光滑）

区块头反序列化速度与区块头大小（以字节为单位）的对比

区块序列化速度与区块大小（以字节为单位）的对比

区块反序列化速度与区块大小（以字节为单位）的对比

完整报告请见此处。

规范

简而言之，Borsh 是一种非自描述的二进制序列化格式。它被设计成将任何对象序列化为一组规范且确定的字节。

基本原则

• 整数是低位字节序；
• 动态容器的大小（如向量、字符串）在值之前以 u32 的形式写入；
• 所有无序容器（哈希表/集合）按键的字典顺序排序（在值相同的情况下按值排序）；
• 结构体按结构体中的字段顺序序列化；
• 枚举使用 u8 为枚举序号，然后存储枚举值内部的数据（如果有的话）。

形式规范

注意

• 一些 Rust 语法部分尚未形式化，如枚举和变体。我们从 syn 类型 反向推导 Rust 语法的 EBNF 形式；
• 我们不得不扩展EBNF的重复，而不是将它们定义为 [ ident_field ':' ident_type ',' ] *，而是将它们定义为 ident_field0 ':' ident_type0 ',' ident_field1 ':' ident_type1 ',' ...，这样我们就可以在伪代码中引用单个元素；
• 我们使用 repr() 函数来表示我们将给定元素的表示写入一个假想的缓冲区。

发布

在您将更改合并到主分支并提高所有三个crate的版本后，是时候正式发布新版本了。

确保 borsh、borsh-derive 和 borsh-derive-internal 都有新的crate版本。然后导航到每个文件夹并按顺序运行（以下顺序）

cd ../borsh-derive-internal; cargo publish
cd ../borsh-derive; cargo publish
cd ../borsh; cargo publish

确保您在主分支上，然后标记代码并推送标签

git tag -a v9.9.9 -m "My superawesome change."
git push origin v9.9.9