Bilrost不对未知字段数据执行这些相同的约束；如果在数据中发现包含模式中未出现的标签的字段，则它不会被视为规范，但解码可能成功。因为这些字段被丢弃，所以它们也没有被强制转换为不同的值，因此承诺得以保持。

设计用于规范性

Bilrost被设计为使几类非规范状态无法表示，从而大大简化了非规范数据的检测。

最大的变化是，顺序编码的消息字段是不可表示的；在protobuf中，这已经是最常见的消息类型的观察行为，但从未被承诺过，原因在此处不太相关（并且将在下面讨论）。这增加了仅当“oneof”（一组互斥字段）具有可能在消息字段的顺序中出现在不同位置的标签号时数据编码的复杂性；在实践中，这种情况相当罕见。

较小的变化是，构成编码核心的varint表示被设计为保证任何给定数字只有一个表示。这可能比传统的LEB128 varint略高，但并不像人们想象的那么多；快速解码LEB128 varint相当复杂，对于大多数varint的最大优化是在值足够小以至于可以适应一个字节时采取捷径，而Bilrost的varint在这一范围内编码相同。

区分解码

在某些应用中，能够将消息编码为一种保证的规范形式，并且在解码时能够区分规范和非规范编码，是非常有价值的。Bilrost可以提供这种功能，并且与其他许多编码相比，其复杂度和开销更低。

在bilrost中，可以推导出扩展特质DistinguishedMessage，它提供了一种特殊的解码模式。在特殊解码模式下的解码包含额外的规范性检查：解码结果可以让我们知道解码的消息数据是否是规范的。任何可以实施特殊解码的消息类型都将始终以完全规范的形式进行编码；不存在“更规范”的备用编码模式。

正式来说，当一个消息类型实现了DistinguishedMessage时，该消息类型的值与所有字节字符串的子集一一对应，每个字节字符串都被认为是该消息值的规范编码。每个不同的字节字符串在特殊解码模式下解码为一个与所有其他此类字节字符串解码的消息值都不同的消息值，或者会在这种模式下产生错误或非规范结果。如果从字节字符串在特殊解码模式下成功且规范地解码出一个消息，并且未对其进行修改，然后重新编码，它将发出相同的字节字符串。

在Rust中，这种对等关系的最佳代理是Eq特质，它表示实现了它的任何类型的所有值之间都存在等价关系。因此，为了在bilrost中实现特殊解码，需要所有字段和消息类型都实现这个特质。

因此，如果存在任何被忽略的字段，bilrost将拒绝推导DistinguishedMessage，因为它们也可能参与类型的相等性。

bilrost以与自动推导的Eq实现相匹配的方式区分类型中的规范值（即，它基于每个组成部分字段的Eq特质进行匹配）。强烈建议，但不是必须的，自动推导相等特质。bilrost并不直接依赖于类型相等性的实现；相反，它作为一个合同护栏，设定了一个最低期望。

正常的（便捷的）解码可能接受其他字节字符串作为给定值的有效编码，例如包含未知字段或非规范编码值的编码[^noncanon]。大多数时候，这是所需的。

[^noncanon]：Bilrost中的“非规范”值编码主要包括那些虽然被编码表示，但被认为值为空的字段。对于消息类型，例如嵌套消息，它还包括包含未知标签字段的报文表示。

为了支持对特殊消息的“正好1:1”期望，某些类型被禁止，在特殊模式下不实现，尽管在理论上它们可以。这主要是指浮点数，它们的相等性语义不兼容。在Bilrost编码中，浮点数以今天大多数计算机的标准IEEE 754二进制格式表示。这伴随着特定的相等性语义规则，这些规则通常在所有语言中都是一致的，并且不形成等价关系。“NaN”值从不彼此相等，也不与自身相等。

规范顺序和特殊表示

Bilrost 指定了大部分制作这些消息模式所需的内容，不仅适用于不同架构和程序，还可以用于其他编程语言。目前有一个小警告：Bilrost 中值的 排序顺序 可能很重要。

在区分解码模式下，规范数据必须始终以排序顺序的 集合 和 映射 来表示。当集合的项类型（或映射的键类型）不是一个具有已标准化排序顺序的简单类型（如整数或字符串）时，项的规范顺序取决于该类型的实现，并且在定义区分类型时必须注意标准化该顺序，以及消息字段的模式。

浮点值与区分解码

等价关系也不足以描述 Bilrost 中区分类型所需的所有属性；不仅必须考虑 值本身 是等价的，还必须 编码 为相同的字节。在编码和解码浮点值时，bilrost 会注意保留 +0.0 和 -0.0 之间的区别，这在 IEEE 754 中被认为是相等的；这 在过去是其他编码的问题。即使并非总是必需，当值在 bilrost 中编码后，再次解码该值将保证产生具有相同位数的相同值。

因此，目前还没有考虑为 Rust 的浮点类型实现区分解码的好主意，这些类型实现了 Eq 和 Ord（如 ordered_float 和 decorum），因为它们仍然认为某些具有 不同位 的值是相等的。任何此类类型的未来实现都必须特别注意统一这些类型中任何等价类的编码表示，并 以可移植的方式标准化，这实际上也会在往返过程中导致一些数据丢失。无法保证这将被认为是有价值的或实现。

如果需要为浮点值的位表示实现区分编码，应首先将其转换为无符号整数，并以这种方式进行编码。这减少了错误的可能性，并使代码更清晰地表明浮点数需要在关心区分表示的代码中特别处理。

使用库

开始使用

要使用 bilrost，我们首先在 Cargo.toml 中将其添加为依赖项，使用 cargo add bilrost 或手动添加

bilrost = "0.1010"

然后，为我们定义的结构类型推导 bilrost::Message

use bilrost::Message;

#[derive(Debug, PartialEq, Message)]
struct BucketFile {
    name: String,
    shared: bool,
    storage_key: String,
}

let foo_file = BucketFile {
    name: "foo.txt".to_string(),
    shared: true,
    storage_key: "public/foo.txt".to_string(),
};

// Encoding data is simple.
let encoded = foo_file.encode_to_vec();
// The encoded data is compact, but not very human-readable.
assert_eq!(encoded, b"\x05\x07foo.txt\x04\x01\x05\x0epublic/foo.txt");

// Decoding data is likewise simple!
let decoded = BucketFile::decode(encoded.as_slice()).unwrap();
assert_eq!(foo_file, decoded);

之后，可以添加更多字段到该结构，它仍然可以解码相同的数据。

# use bilrost::Message;
#[derive(Debug, Default, PartialEq, Message)]
struct BucketFile {
    #[bilrost(1)]
    name: String,
    #[bilrost(5)]
    mime_type: Option<String>,
    #[bilrost(6)]
    size: Option<u64>,
    #[bilrost(2)]
    shared: bool,
    #[bilrost(3)]
    storage_key: String,
    #[bilrost(4)]
    bucket_name: String,
}

let new_file = BucketFile::decode(
    b"\x05\x07foo.txt\x04\x01\x05\x0epublic/foo.txt".as_slice(),
)
.unwrap();
assert_eq!(
    new_file,
    BucketFile {
        name: "foo.txt".to_string(),
        shared: true,
        storage_key: "public/foo.txt".to_string(),
        ..Default::default()
    }
);

包特征

bilrost 包有几个可选功能

• "std"（默认）：提供对 HashMap 和 HashSet 的支持。
• "derive"（默认）：包含 bilrost-derive 包并重新导出其宏。如果正常使用 bilrost，则不太可能禁用此功能。
• "detailed-errors"（默认值）: 消息返回的解码错误类型将在解码数据中遇到错误的精确字段路径上提供更多信息。禁用此功能后，错误更难以理解，但可能更小、更快。
• "auto-optimize"（默认值）: 对一些性能相关实现细节做出一些自动选择。相关的功能可以作为分析和实验的有用控制，并在Cargo.toml中进行说明。大多数用例应启用此功能。
• "no-recursion-limit": 移除旨在防止数据过度嵌套的递归限制。
• "extended-diagnostics": 通过添加一个小依赖项，在派生和派生实现不起作用时尝试提供更好的编译时诊断。有点实验性质。
• "arrayvec": 提供对arrayvec::ArrayVec的第一方支持
• "bytestring": 提供对bytestring::Bytestring的第一方支持
• "hashbrown": 提供对hashbrown::{HashMap, HashSet}的第一方支持
• "smallvec": 提供对smallvec::SmallVec的第一方支持
• "thin-vec": 提供对thin_vec::ThinVec的第一方支持
• "tinyvec": 提供对tinyvec::{ArrayVec, TinyVec}的第一方支持

no_std 支持

禁用 "std" 功能后，bilrost 具有完整的 no_std 支持。如果需要，可以通过启用 "hashbrown" 功能来提供与 no_std 兼容的哈希映射。

要启用 no_std 支持，请禁用 bilrost（以及如果使用，请禁用 bilrost-types）中的 std 功能。

[dependencies]
bilrost = { version = "0.1010", default-features = false, features = ["derive"] }

派生宏

我们现在可以导入和使用其特性和派生宏。主要有三个

• Message: 这是基本的工作单元。为结构体派生此功能以启用将它们编码和解码为二进制数据。
• Enumeration: 这是一个派生功能，而不是特性，它实现了使用 bilrost 对枚举类型进行编码的支持。枚举不得有字段，并且其每个变体将对应于一个不同的 u32 值，该值将在编码中代表它。
• Oneof: 这是一个特性和派生宏，用于表示消息结构体中的互斥字段。每个变体必须有一个字段，并且每个变体都必须有一个唯一的字段标签分配给它，同时在 oneof 中以及在它是其一部分的消息中。具有派生自 Oneof 的类型除了在 Message 结构体（或具有派生自 Message）时外，没有对库用户有用的 bilrost API。

派生 Message

可以派生 Message 特性，以便将几乎任何结构体编码为 Bilrost 消息，只要其字段类型得到支持。

如果没有其他指定，字段将按照在结构体中指定的顺序连续标记。如果未指定，具有命名字段的结构的字段从 1 开始标记，而具有匿名字段的元组结构的字段从 0 开始编号（与它们的 Rust 索引名相匹配）。

标签也可以显式指定。如果一个字段的标签是唯一提供的属性，则可以将标签号以“bilrost”属性的唯一内容的形式提供，如 #[bilrost(1)]。如果包含其他属性，则必须通过名称指定“tag”属性；例如，如 #[bilrost(tag(1), encoding(fixed))]。 “tag”属性也可以写成 tag = 1 或 tag = "1"。

我们可以通过在空缺后的第一个字段上指定要跳过的标签号来跳过已预留的标签或存在标签值之间的空缺。接下来的字段将从下一个数字开始连续标记。

在定义用于互操作的消息类型或字段可能被添加、删除或重新排列时，最好显式指定结构体中所有字段的标签，但这不是强制性的。

use bilrost::{Enumeration, Message};

#[derive(Clone, PartialEq, Message)]
struct Person {
    #[bilrost(tag = 1)]
    pub id: String, // tag=1
    // NOTE: Old "name" field has been removed
    // pub name: String,
    // given_name has tag 6
    #[bilrost(6)]
    pub given_name: String,
    // family_name has tag 7
    pub family_name: String,
    // formatted_name has tag 8
    pub formatted_name: String,
    // age has tag 3
    #[bilrost(tag = "3")]
    pub age: u32,
    // height has tag 4
    pub height: u32,
    // gender has tag 5
    #[bilrost(enumeration(Gender))]
    pub gender: u32,
    // NOTE: Skip to less commonly occurring fields
    #[bilrost(tag(16))]
    pub name_prefix: String, // has tag 16  (eg. mr/mrs/ms)
    pub name_suffix: String, // has tag 17  (eg. jr/esq)
    pub maiden_name: String, // has tag 18
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Enumeration)]
#[non_exhaustive]
pub enum Gender {
    Unknown = 0,
    Female = 1,
    Male = 2,
    Nonbinary = 3,
}

Oneof 字段

Bilrost 消息可以具有互斥字段集，一次只能存在其中一个。这些由每个变体有一个字段并分配一个字段标签的 enum 类型表示；然后可以使用 Oneof derive 宏来生成实现，允许 oneof 包含在消息中。

use bilrost::{Message, Oneof};

#[derive(Oneof)]
enum NameOrUUID {
    #[bilrost(2)]
    Name(String),
    #[bilrost(tag(3), encoding(plainbytes))]
    UUID([u8; 16]),
}

#[derive(Message)]
struct Widget {
    #[bilrost(1)]
    id: u32,
    #[bilrost(oneof(2, 3))]
    label: Option<NameOrUUID>,
    #[bilrost(4)]
    description: String,
}

当 oneof 包含在消息中时，必须使用“oneof”属性声明它，提供所有字段标签的逗号分隔列表。（此属性也可以写成 oneof = "2, 3"。）[^tagranges] 由于 derive 宏在运行时无法访问字段类型的定义，因此它无法知道这些标签号是什么，但是在此属性中声明的标签列表和 oneof 实际拥有的标签列表在编译时进行静态检查以确保相等。

use bilrost::{Message, Oneof};

#[derive(Oneof)]
enum Abc {
    #[bilrost(1)]
    A(String),
    #[bilrost(2)]
    B(i64),
    #[bilrost(3)]
    C(bool),
}

#[derive(Default, Message)]
struct TagsDontMatch {
    #[bilrost(oneof(1, 2))] // These tags don't match the oneof!
    label: Option<Abc>,
}

// In older versions of rust, the build may not fail until the message trait is
// actually used somewhere.
let _ = TagsDontMatch::default().encoded_len();

[^tagranges]：在oneof属性和reserved_tags属性中指定标签完整列表的方式相同：整个列表以逗号分隔，每个项可以是单个标签号，也可以是从最小到最大值的包含范围，范围值之间用连字符分隔（例如1-5）。对于reserved_tags和oneof，以下都是完全等价的：1, 2, 3, 4, 5；1-5；4, 5, 1-3

oneof中的字段标签必须是唯一的，既要在oneof内部，也要在包含它的任何消息中唯一。Oneof变体只能包含可以嵌套的类型（因此不支持“未打包”的集合）。从机制上讲，oneof的工作方式与为每个变体都有一个Option<T>字段的Option相同，但最多只有一个可以是Some。

在上面的示例中，NameOrUUID oneof必须嵌套在Option中，才能使其能够表示没有任何字段存在的空状态。也可以在oneof枚举中包含最多一个单元变体。任何这样的变体都将用于表示其空状态。

use bilrost::{Message, Oneof};

#[derive(Oneof)]
enum NameOrUUID {
    #[bilrost(2)]
    Name(String),
    #[bilrost(tag(3), encoding(plainbytes))]
    UUID {
        octets: [u8; 16],
    },
    Neither,
}

#[derive(Message)]
struct Widget {
    #[bilrost(1)]
    id: u32,
    #[bilrost(oneof(2, 3))]
    label: NameOrUUID,
    #[bilrost(4)]
    description: String,
}

当oneof枚举类型具有空变体时，它可以直接包含在消息中；当它没有空变体时，它只能嵌套在Option中。

为枚举推导Message

Message和DistinguishedMessage也可以为具有相应oneof实现的枚举推导。它们以消息形式编码和解码，这些消息最多只有一个字段，就像类型是一个只包含枚举且每个变体对应一个字段的#[bilrost(oneof(..))]属性的Message一样。

use bilrost::{Message, Oneof};

#[derive(Oneof, Message)]
enum Maybe {
    Nope,
    #[bilrost(1)]
    Yes(String),
    #[bilrost(2)]
    Very(String),
}

/// This struct encodes exactly the same as Maybe does with its own `Message`
/// impl; deriving `Message` on the enum just saves some work.
#[derive(Message)]
struct WrappedMaybe {
    #[bilrost(oneof(1, 2))]
    maybe: Maybe,
}

use bilrost::{Message, Oneof};

#[derive(Oneof, Message)]
//              ^^^^^^^ Error: Message can only be derived for Oneof enums
//                             that have an empty variant.
enum AB {
    #[bilrost(1)]
    A(bool),
    #[bilrost(2)]
    B(bool),
}

use bilrost::{Message, Oneof};

#[derive(Oneof)]
enum AB {
    #[bilrost(1)]
    A(bool),
    #[bilrost(2)]
    B(bool),
}

#[derive(Message)]
struct WrappedAB(#[bilrost(oneof(1, 2))] Option<AB>);

# use bilrost::Message;
#[derive(Message)]
struct Foo {
    #[bilrost(encoding(general))]
    name: String,
}

# use bilrost::Message;
#[derive(Message)]
struct Bar(
    // This is the same type as "general"
    #[bilrost(encoding = "::bilrost::encoding::General")] String,
);

assert_eq!(
    Bar("bar".to_string()).encode_to_vec(),
    b"\x01\x03bar".as_slice()
);

# use bilrost::Message;
#[derive(Message)]
#[bilrost(reserved_tags(2, 6-10, 25))]
struct Foo {
    #[bilrost(tag(5), encoding(general))]
    name: String,
    age: int64, // Oops! Uses tag 6! Compile error
}

# use bilrost::Message;
#[derive(Message)]
//       ^^^^^^^ the trait `Encoder<Vec<Tree>>` is not implemented for `General`
struct Tree {
    name: String,
    children: Vec<Tree>,
}

# use bilrost::Message;
#[derive(Message)]
struct Tree {
    name: String,
    #[bilrost(recurses)]
    children: Vec<Tree>,
}

use bilrost::{
    DistinguishedMessage, DistinguishedOneof, Message, Oneof,
    WithCanonicity,
};
use bytes::Bytes;
use std::collections::BTreeMap;

#[derive(Debug, PartialEq, Eq, Oneof, DistinguishedOneof)]
enum PubKeyMaterial {
    Empty,
    #[bilrost(1)]
    Rsa(Bytes),
    #[bilrost(2)]
    ED25519(Bytes),
}

use PubKeyMaterial::*;

#[derive(Debug, PartialEq, Eq, Message, DistinguishedMessage)]
struct PubKey {
    #[bilrost(oneof(1, 2))]
    key: PubKeyMaterial,
    #[bilrost(3)]
    expiry: i64, // See also: `bilrost_types::Timestamp`
}

#[derive(Debug, Default, PartialEq, Eq, Message, DistinguishedMessage)]
struct PubKeyRegistry {
    keys_by_owner: BTreeMap<String, PubKey>,
}

let mut registry = PubKeyRegistry::default();
registry.keys_by_owner.insert(
    "Alice".to_string(),
    PubKey {
        key: ED25519(Bytes::from_static(b"not a secret")),
        expiry: 1600999999,
    },
);
registry.keys_by_owner.insert(
    "Bob".to_string(),
    PubKey {
        key: Rsa(Bytes::from_static(b"pkey")),
        expiry: 1500000001,
    },
);
let encoded = registry.encode_to_vec();

// The binary of this encoded message breaks down as follows:
//
// (The first and only field, containing a map from String to PubKey)
// 05 - field key: tag 0+1 = 1, wire type 1 = length-delimited
//   2c - length: 44 bytes
//     (The key of the first map item, a String value)
//     05 - length: 5 bytes
//       "Alice"
//     (The value of the first map item, a PubKey message)
//     14 - length: 20 bytes
//       (The "ED25519" variant of the PubKeyMaterial oneof)
//       09 - field key: tag 0+2 = 2, wire type 1 = length-delimited
//         (A String value)
//         0c - length: 12 bytes
//           "not a secret"
//       (The "expiry" field of the PubKey message, an i64)
//       04 - field key: tag 2+1 = 3, wire type 0 = varint
//         fec7e9f50a - varint 3201999998, which is +1600999999 in zig-zag
//     (The key of the second map item, a string value)
//     03 - length: 3 bytes
//       "Bob"
//     (The value of the second map item, another PubKey message)
//     0c - length: 12 bytes
//       (The "RSA" variant of the PubKeyMaterial oneof)
//       05 - field key: tag 0+1 = 1, wire type 1 = length-delimited
//         (A String value)
//         04 - length: 4 bytes
//           "pkey"
//       (The "expiry" field of the PubKey message, an i64)
//       08 - field key: tag 1+2 = 3, wire type 0 = varint
//         82bbc0950a - varint 3000000002, which is +1500000001 in zig-zag

assert_eq!(
    encoded,
    b"\x05\x2c\
      \x05Alice\x14\x09\x0cnot a secret\x04\xfe\xc7\xe9\xf5\x0a\
      \x03Bob\x0c\x05\x04pkey\x08\x82\xbb\xc0\x95\x0a"
        .as_slice()
);

let decoded = PubKeyRegistry::decode_distinguished(encoded.as_slice())
    .canonical() // Check that the decoded data was canonical
    .unwrap();
assert_eq!(registry, decoded);

#[derive(Clone, PartialEq, Eq, bilrost::Enumeration)]
enum SimpleEnum {
    Unknown = 0,
    A = 1,
    B = 2,
    C = 3,
}

const FOUR: u32 = 4;

#[derive(Clone, PartialEq, Eq, bilrost::Enumeration)]
#[repr(u8)] // The type needn't have a u32 repr
enum ComplexEnum {
    One = 1,
    #[bilrost = 2]
    Two,
    #[bilrost(3)]
    Three,
    #[bilrost(FOUR)]
    Four,
    // When both discriminant and attribute exist, bilrost uses the attribute.
    #[bilrost(5)]
    Five = 8,
}

# use bilrost::Enumeration;
#[derive(Clone, PartialEq, Eq, Enumeration)]
enum Foo {
    A = 1,
    #[bilrost(1)] // error: unreachable pattern
    B = 2,
}

def encode_varint(n: int) -> bytes:
    assert 0 <= n < 2**64
    bytes_to_encode = []
    # Encode up to 8 preceding bytes
    while n >= 128 and len(bytes_to_encode) < 8:
        bytes_to_encode.append(128 + (n % 128))
        n = (n // 128) - 1
    # Always encode at least one byte
    bytes_to_encode.append(n)
    return bytes(bytes_to_encode)


def decode_varint_from_byte_iterator(it: Iterable[int]) -> int:
    n = 0
    for byte_index, byte_value in enumerate(it):
        assert 0 <= byte_value < 256
        n += byte_value * (128**byte_index)
        if byte_value < 128 or byte_index == 8:
            # Varints encoding values greater than 64 bits MUST be rejected
            if n >= 2**64:
                raise ValueError("invalid varint")
            return n
    # Reached end of data before the end of the varint
    raise ValueError("varint truncated")

use bilrost::Message;

#[derive(Message)]
struct Foo<T>(#[bilrost(encoding(fixed))] T);

// Both of these messages encode as the bytes `b'\x06\x01\x02\x03\x04'`
assert_eq!(
    Foo(0x04030201u32).encode_to_vec(),
    Foo([1u8, 2, 3, 4]).encode_to_vec(),
);