自定义二进制文件格式需权衡可维护性、跨平台兼容性与解析鲁棒性，关键在字节序统一、结构体显式对齐、版本号前置及变长数据长度前缀。
自定义二进制文件格式不是“设计一个漂亮结构”就完事的；它本质是**在可维护性、跨平台兼容性和解析鲁棒性之间做权衡**。多数人踩坑不是因为不会写 fwrite，而是没想清楚字节序、对齐、版本演化这三件事。
struct 内存布局 ≠ 文件格式布局
C++ 的 struct 直接用 fwrite(&s, sizeof(s), 1, fp) 写入，看似简单，实则埋雷：
-
#pragma pack(1)必须显式加，否则编译器按默认对齐（如 x86_64 下int64_t对齐到 8 字节，中间可能插填充字节） - 不同平台默认对齐策略不同，同一份代码在 Windows MSVC 和 Linux GCC 下可能写出不同字节流
- 含指针或 STL 容器（如
std::string、std::vector）的 struct 绝对不能直接序列化——它们只存内存地址或内部堆指针
正确做法是定义纯 POD（Plain Old Data）结构体，并手动控制字段顺序和大小：
struct Header {
uint32_t magic; // 0x464F524D ('FORM')
uint32_t version; // 1
uint64_t data_size; // 实际数据长度
} __attribute__((packed)); // GCC/Clang；MSVC 用 #pragma pack(1)
字节序不统一，跨平台读写必错
x86/x64 是小端（little-endian），ARM64 多数也是小端，但网络协议和部分嵌入式平台用大端（big-endian）。若不做转换，Linux 写的文件在某些嵌入式设备上读出来全是错值。
立即学习“C++免费学习笔记（深入）”；
- 永远用固定端序写入：推荐网络字节序（大端），即用
htons()/htonl()/htobe64()（需<endian.h></endian.h>或自实现） - 读取时统一用对应反向函数：
ntohs()/ntohl()/be64toh() - 不要依赖
__BYTE_ORDER__宏做条件编译——运行时检测更可靠，尤其动态库场景
示例（写入 uint32_t val = 0x12345678）：
uint32_t net_val = htonl(val); fwrite(&net_val, sizeof(net_val), 1, fp);
没有版本号的二进制格式，等于没有格式
一旦业务扩展（比如加个时间戳字段、把 float 换成 double），旧程序读新文件直接崩溃或静默错误。必须把版本信息放在文件开头固定位置。
- 版本号建议用独立字段（如
uint16_t format_version），别塞进 magic 字段高字节 - 解析逻辑要按版本分支：
if (hdr.version == 1) { ... } else if (hdr.version == 2) { ... } - 预留
uint32_t reserved[4]字段，方便未来加字段不破坏偏移 - 拒绝解析未知版本——报错退出，而不是尝试“尽力而为”解析
字符串和变长数据怎么存？别用 '\0' 结尾
二进制文件里混入 C 风格字符串（char name[32]）极难维护：长度固定浪费空间、超长截断无提示、含 '\0' 会提前终止解析。
- 统一用“长度前缀 + 字节流”：先写
uint32_t len，再写len字节原始内容（UTF-8 编码） - 避免
std::string::c_str()直接写——它不保证结尾 '\0' 后无脏数据，且长度不可控 - 如果必须固定长度字段（如 ID），用
std::array<char></char>并手动 memset 填 0，读取后用std::string_view(data.data(), strnlen(data.data(), data.size()))安全构造视图
写入字符串示例：
std::string s = "hello"; uint32_t len = static_cast<uint32_t>(s.length()); fwrite(&len, sizeof(len), 1, fp); fwrite(s.data(), 1, len, fp);
真正麻烦的从来不是“怎么把数据塞进文件”，而是“三年后别人（或你自己）拿到这个文件，能否不查源码就安全还原出原始语义”。magic 字段、版本号、显式长度、固定端序——这些不是仪式感，是降低后续维护熵值的最小成本。
