第26.13章:序列化与二进制格式
1. 没有独立的序列化框架
fast_io 没有带 schema 注册、反射或运行期类型注册表的序列化框架。 二进制格式用和其他 I/O 一样的三件工具写:标量用操纵器,blob 用字节操作, 记录用长度或分隔符分帧。
重要的部分是显式决定线格式。不要把一个结构体的地址强转成 std::byte*
直接写:padding、对齐和原生端序不是协议的一部分。
每个字段用确定的宽度和字节序写。
2. 端序辅助
| 条目 | 含义 | 模块 |
|---|---|---|
byte_swap(value) |
反转无符号整数的字节序。 | fast_io |
little_endian(value) |
把原生整数转成小端表示。 | fast_io |
big_endian(value) |
把原生整数转成大端表示。 | fast_io |
le_put<N>(value) |
写一个 N 位小端整数。 |
头文件侧 |
be_put<N>(value) |
写一个 N 位大端整数。 |
头文件侧 |
le_get<N>(ref)、be_get<N>(ref) |
按选定字节序读一个 N 位整数。 |
头文件侧 |
lebe_put<endian, N>(value) |
le_put/be_put 背后的通用形式。 |
头文件侧 |
iec559_le_put、iec559_be_put |
IEEE-754 浮点字节序辅助。 | 头文件侧 |
auto const wire{::fast_io::big_endian(value)};
::fast_io::operations::write_all_bytes(
out, reinterpret_cast<::std::byte const *>(&wire), sizeof(wire));
转换函数是 constexpr,并处理宿主原生字节序,包括非小端/非大端目标。
le_put/le_get 家族是格式化器层替代方案:
通过 print/scan 读写,而不是原始字节复制。
3. LEB128
LEB128 是可变长度整数编码。fast_io 以一对操纵器提供它:
::fast_io::io::print(out, ::fast_io::mnp::leb128_put(size));
::std::uint64_t decoded{};
::fast_io::io::scan(in, ::fast_io::mnp::leb128_get(decoded));
| 条目 | 方向 | 模块 |
|---|---|---|
leb128_put(value) |
写 | fast_io |
leb128_get(ref) |
读 | fast_io |
编码器处理有符号和无符号整数。解码器检查截断和溢出; 畸形流是解析错误,不是部分值。
4. WebAssembly 编码
WebAssembly 辅助是同一组原语上的头文件侧别名:
| 条目 | 编码 |
|---|---|
wasm_varint_put、wasm_varint_get |
LEB128 varint。 |
wasm_uint32_put、wasm_uint32_get |
32 位小端。 |
wasm_uint64_put、wasm_uint64_get |
64 位小端。 |
wasm_float_put、wasm_float_get |
IEEE-754 小端浮点。 |
它们不在模块导出列表里。需要时包含 #include <fast_io.h>。
5. 固定大小字节窗口
正好 N 字节的记录用 read_all_bytes /
write_all_bytes。已知长度的文本 token 用 str_get_all(ref, n):
::std::byte header[16];
::fast_io::operations::read_all_bytes(in, header, sizeof(header));
::std::byte payload[64];
::fast_io::operations::write_all_bytes(out, payload, sizeof(payload));
这些操作在无法填满整个窗口时失败。短读不会被悄悄当成完整记录; 短写不会被悄悄当成完整消息。
6. 一个分帧二进制记录
长度前缀记录是避免分隔符歧义的最简单格式。长度是 LEB128 varint,body 是原始字节:
void write_record(::fast_io::obuf_file &out,
::fast_io::span<::std::byte const> body)
{
::fast_io::io::print(out, ::fast_io::mnp::leb128_put(body.size()));
::fast_io::operations::write_all_bytes(out, body.data(), body.size());
}
std::uint64_t length{};
::fast_io::io::scan(in, ::fast_io::mnp::leb128_get(length));
::fast_io::vector<::std::byte> body;
body.resize(length);
::fast_io::operations::read_all_bytes(in, body.data(), body.size());
两条规则让它安全。第一,在分配之前用最大值检查长度。 第二,短 body 是截断记录,要失败;不要处理部分 payload。 同一模式适用于网络帧、文件记录和内存缓冲区。
7. 不要靠强转序列化
- 不要把结构体按字节写。 padding、对齐和字段顺序是实现细节。
- 不要依赖原生端序。 每个字段显式选择小端或大端。
- 不要从指针字段
memcpy。 用长度序列化指向的数据。 - 不要把 union 当线格式。 活跃成员是手工维护的; 带标签的编码更清晰、更可移植。
- 不要信任长度前缀。 分配前给它上界。
8. 模块与头文件边界
fast_io 模块导出 byte_swap、little_endian、
big_endian、leb128_put、leb128_get
以及字节读写操作。le_put/le_get 家族、IEEE-754 辅助、
WebAssembly 辅助和 str_get_all 目前在头文件侧。
要点
- fast_io 通过操纵器和字节操作序列化,不是 schema 框架。
byte_swap、little_endian和big_endian由模块导出;le_put/le_get在头文件侧。leb128_put/leb128_get由模块导出,处理有符号和无符号值。- WebAssembly varint 和浮点辅助是头文件侧别名。
- 精确窗口用固定大小字节操作;短读和短写会失败。
- 长度前缀记录,先验证上界,再读 body。
- 永远不要把结构体或 union 当作它的内存字节镜像。