1. 引言为什么还需要一个老派的序列化库在 Protobuf、flatbuffers、Apache Arrow 等重量级序列化方案大行其道的今天cereal 依然占据着一个不可替代的位置当你想序列化一个纯 C 对象却不想写 .proto 文件、不想跑代码生成器、不想引入几十 MB 的依赖时cereal 是让你 10 分钟内跑通全流程的答案。cereal 由南加州大学USC的 Shane Grant 等人开发托管于 GitHub 的 USCiLab/cereal 仓库采用 BSD-3-Clause 许可可自由用于商业项目。它的核心承诺只有一句话仅需包含头文件即可让任意 C 类型包括 STL 容器、智能指针、继承多态在二进制 / JSON / XML三种格式之间来回存取全程无需 IDL、无需注册表、无需额外代码生成。本文将从使用优点、适用场景、具体使用方式、常见坑点四个维度展开并在最后与系列中已有的 Protobuf / flatbuffers / Apache Arrow / nlohmann-json / simdjson 篇目做定位对照。2. 使用优点2.1 header-only 零依赖接入成本趋近于零cereal 的全部实现都在头文件中不依赖 Boost、不依赖编译期生成的库文件。集成方式只有两种把 include/cereal 目录拷进项目并添加 include 路径或通过 CMake find_package / FetchContent 拉取。对于公司内网无法访问外网、包管理器受限的封闭环境直接拷头文件是唯一零摩擦的选项。2.2 无需 IDL类型即接口与 Protobuf / flatbuffers 必须编写 .proto / .fbs 并使用 protoc / flatc 生成代码不同cereal 直接在 C 类型上就地定义序列化逻辑。你只需要为自定义类型提供一个 serialize 模板成员函数或自由函数struct Point { double x 0, y 0; template class Archive void serialize(Archive ar) { ar(x, y); } // 一行搞定 };新增字段、删除字段、重构类型结构改动都发生在 C 代码本身没有跨语言代码生成再同步的撕裂感。2.3 三种归档格式一套代码通吃同一个 serialize 函数可以同时服务 BinaryArchive紧凑二进制、JSONArchive人类可读文本、XMLArchive带类型约束的标记语言。切换格式只需要替换 Archive 类型与输入输出流业务代码零改动——这是模板化 Archive设计的最大红利。2.4 与 STL 容器、智能指针、继承多态开箱即用cereal 为 std::vector、std::map、std::set、std::unordered_map、std::string、std::optionalC17、std::variantC17等几乎所有常用容器与工具类型提供了现成的序列化支持头文件位于 cereal/types/。更难得的是智能指针语义std::shared_ptr 序列化时自动维护同一对象只存一份的引用关系反序列化后多个指针重新指向同一对象std::unique_ptr 也能正确转移所有权。多态支持通过 cereal/types/polymorphic.hpp 与 CEREAL_REGISTER_TYPE 宏可以让 std::shared_ptrBase 存出 Derived 的真实类型并在读取时自动还原为 Derived。2.5 版本化序列化与分支 Archive兼容性问题的正统解法长期存储的场景最怕旧数据读不进来。cereal 提供两件武器类版本号CEREAL_CLASS_VERSION(MyClass, 2) 会在二进制流中记录版本serialize(ar, version) 按版本分支读取旧存档永远可读。分支 ArchiveArchive branchingserialize 是模板可以针对不同 Archive 类型给出不同行为——例如 JSON 输出带名字cereal::make_nvp二进制输出直接裸值互不干扰。2.6 易用性与现代 C 风格全部基于 C11 模板与可变参数包实现代码风格与标准库一致。不需要注册任何全局工厂多态除外普通类型天然可用。错误处理文本格式解析失败抛出 cereal::Exception可捕获后定位字段。单头文件核心 cereal/cereal.hpp 只有几千行阅读源码学习模板技巧也很方便。3. 使用场景场景为什么适合 cereal典型形态配置文件持久化JSON/XML 人类可读、可手改、可 diff游戏/工具链的 settings.json、项目模板配置网络传输对象二进制格式紧凑、无需 IDL 即可让 C/S 两端共享结构体头文件局域网工具、内部服务间 C 对象直传游戏存档支持智能指针/容器/多态存档逻辑贴近游戏对象模型版本化保证旧存档兼容RPG 角色存档、关卡编辑器快照缓存 / 消息体header-only 便于嵌入各种模块文本格式便于调试抓包内存缓存落盘、进程间消息体跨模块数据交换同一代码库内不同模块共享结构体省去中间格式转换插件与主程序、编辑器与运行时不适用场景跨语言互通Python/Java/Go 读取 cereal 二进制需要另写解析器JSON 格式除外、极致性能与零拷贝应选 flatbuffers/Apache Arrow、超大消息的 schema 演进治理应选 Protobuf。3.1 与主流方案的定位对比维度cerealProtobufflatbuffersApache Arrownlohmann/json是否需要 IDL / 代码生成否是.proto protoc是.fbs flatc否但需按 Arrow 类型体系手工构建否接入成本最低拷头文件中工具链 生成代码中工具链 生成代码高预编译库低header-only序列化格式二进制/JSON/XML二进制Varint/zigzag二进制零拷贝二进制列式IPC/ParquetJSON 文本跨语言差C 专属强强强强性能中上二进制紧凑高极高零拷贝读取高列式批量中低文本解析动态 schema 演进版本号 分支字段号 前向兼容字段号 前向兼容有限Arrow Schema天然动态智能指针/继承多态原生支持需 message 嵌套模拟需 union 模拟需手动编码需手动编码适合场景C 内部快速持久化跨语言 RPC高频零拷贝读取数据分析/批量交换配置/调试友好4. 具体使用方式4.1 集成CMake / vcpkg / FetchContent方式 Avcpkg推荐包管理vcpkg install cerealCMake 中find_package(cereal REQUIRED) target_link_libraries(my_app PRIVATE cereal::cereal)方式 BFetchContent构建期拉取include(FetchContent) FetchContent_Declare(cereal GIT_REPOSITORY https://github.com/USCiLab/cereal.git GIT_TAG v1.3.2 GIT_SHALLOW TRUE) FetchContent_MakeAvailable(cereal) target_link_libraries(my_app PRIVATE cereal::cereal)方式 C纯头文件拷贝# 将仓库 include/cereal 目录复制到第三方库目录即可 # 编译器添加 -I path/include4.2 基本类型与自定义结构体#include cereal/archives/json.hpp #include cereal/types/string.hpp #include fstream struct Person { std::string name; int age 0; double height 0.0; template class Archive void serialize(Archive ar) { ar(CEREAL_NVP(name), CEREAL_NVP(age), CEREAL_NVP(height)); } }; int main() { Person p{Alice, 30, 1.72}; // 写 JSON { std::ofstream os(person.json); cereal::JSONOutputArchive oar(os); oar(cereal::make_nvp(person, p)); } // 读 JSON Person q; { std::ifstream is(person.json); cereal::JSONInputArchive iar(is); iar(cereal::make_nvp(person, q)); } return 0; }提示JSON / XML 归档要求变量有名字推荐 CEREAL_NVP(x)自动使用变量名或 cereal::make_nvp(custom_name, x)。4.3 STL 容器与智能指针#include cereal/types/vector.hpp #include cereal/types/map.hpp #include cereal/types/memory.hpp struct GameState { std::vectorint scores; std::mapstd::string, int highScores; std::shared_ptrPlayer currentPlayer; // Player 定义见下 template class Archive void serialize(Archive ar) { ar(CEREAL_NVP(scores), CEREAL_NVP(highScores), CEREAL_NVP(currentPlayer)); } };shared_ptr 的引用语义在 cereal 中自动生效两次序列化同一对象不会重复落盘读回后指针身份保持一致。4.4 多态与继承#include cereal/types/memory.hpp #include cereal/types/polymorphic.hpp struct Animal { std::string name; virtual ~Animal() default; template class Archive void serialize(Archive ar) { ar(CEREAL_NVP(name)); } }; struct Dog : Animal { int barkVolume 0; template class Archive void serialize(Archive ar) { ar(cereal::base_classAnimal(this), CEREAL_NVP(barkVolume)); } }; // 关键在 .cpp或唯一头文件中注册派生类型 CEREAL_REGISTER_TYPE(Dog);保存时以基类指针持有派生类std::shared_ptrAnimal pet std::make_sharedDog(); pet-name Rex; static_castDog*(pet.get())-barkVolume 8; std::ofstream os(pet.bin); cereal::BinaryOutputArchive oar(os); oar(pet); // 写出的流中包含真实类型信息读回自动还原为 Dog注意多态序列化需要开启 RTTI编译器默认开启且 Animal 必须有虚析构函数CEREAL_REGISTER_TYPE 放在单个翻译单元内避免重复定义链接错误。4.5 Binary / JSON / XML 三种归档切换同一份 serialize 无需任何改动只需更换 Archive 类型与流// 二进制 std::ofstream os(data.bin); cereal::BinaryOutputArchive oar(os); oar(data); // JSON std::ofstream os(data.json); cereal::JSONOutputArchive oar(os); oar(cereal::make_nvp(data, data)); // XML std::ofstream os(data.xml); cereal::XMLOutputArchive oar(os); oar(cereal::make_nvp(data, data));输入侧对应 BinaryInputArchive / JSONInputArchive / XMLInputArchive。4.6 save / load 对称设计当需要读和写不同逻辑或构造带 const 成员的类型时可以将 serialize 拆成 save / load 对class EncryptedBox { std::string payload; public: EncryptedBox() default; explicit EncryptedBox(std::string s) : payload(std::move(s)) {} template class Archive void save(Archive ar) const { ar(CEREAL_NVP(payload)); // 保存前可加密 } template class Archive void load(Archive ar) { ar(CEREAL_NVP(payload)); // 读取后可解密 } };cereal 自动识别 save / load 对并完成对称调度与 serialize 二选一即可。4.7 版本化与分支 Archive 实战版本化新增字段时用版本号保护旧存档的兼容性#include cereal/cereal.hpp struct UserProfile { std::string name; std::string email; // v2 新增 int level 1; // v1 已有 template class Archive void serialize(Archive ar, const std::uint32_t version) { ar(CEREAL_NVP(name)); if (version 1) ar(CEREAL_NVP(level)); if (version 2) ar(CEREAL_NVP(email)); } }; CEREAL_CLASS_VERSION(UserProfile, 2);分支 Archive针对文本/二进制给出不同输出策略template class Archive void serialize(Archive ar) { if (cereal::traits::is_text_archiveArchive::value) { // JSON/XML带名字可读性好 ar(CEREAL_NVP(x), CEREAL_NVP(y), CEREAL_NVP(z)); } else { // Binary裸值最紧凑 ar(x, y, z); } }4.8 可编译完整示例集成全部要点// demo.cpp —— 编译g -stdc17 demo.cpp -o demo cereal 仅需 include 路径 #include cereal/archives/binary.hpp #include cereal/archives/json.hpp #include cereal/types/string.hpp #include cereal/types/vector.hpp #include cereal/types/memory.hpp #include cereal/types/polymorphic.hpp #include fstream #include iostream struct Weapon { std::string name; int damage 0; template class Archive void serialize(Archive ar) { ar(CEREAL_NVP(name), CEREAL_NVP(damage)); } }; struct Character { std::string name; std::vectorWeapon weapons; std::shared_ptrWeapon equipped; // 智能指针 template class Archive void serialize(Archive ar) { ar(CEREAL_NVP(name), CEREAL_NVP(weapons), CEREAL_NVP(equipped)); } }; int main() { Character hero; hero.name Knight; hero.weapons {{Sword, 12}, {Shield, 3}}; hero.equipped std::make_sharedWeapon(Weapon{Sword, 12}); // 二进制存档 { std::ofstream os(save.bin); cereal::BinaryOutputArchive ar(os); ar(CEREAL_NVP(hero)); } // 读回 Character restored; { std::ifstream is(save.bin); cereal::BinaryInputArchive ar(is); ar(CEREAL_NVP(restored)); } std::cout restored.name has restored.weapons.size() weapons, equipped: restored.equipped-name \n; return 0; }5. 常见坑点与 FAQ 速查表问题原因 / 解决方案1JSON/XML 报 variable with no name文本归档要求命名改用 CEREAL_NVP(x) 或 make_nvp二进制归档无此限制2反序列化失败无默认构造函数cereal 反序列化默认先构造再填充无默认构造的类型需用 load_and_construct 或自定义 load3多态类型读回时抛 Exception未注册类型忘记 CEREAL_REGISTER_TYPE(Derived)或注册宏所在翻译单元未链接4链接错误CEREAL_REGISTER_TYPE 重复定义宏应放在单个 .cpp 中头文件中用 CEREAL_REGISTER_TYPE_WITH_NAME 并确保唯一5二进制跨版本存档读不了为类加 CEREAL_CLASS_VERSION在 serialize(ar, version) 中按版本分支6基类指针读回后丢失派生数据基类需虚析构 派生类注册 serialize 中调用 cereal::base_classBase(this)7文本归档体积大、性能差换成 BinaryArchive仅调试/配置场景用 JSON/XML8序列化 std::unique_ptr 报错需包含 cereal/types/memory.hppcereal 会转移所有权原指针读回后失效属预期9cereal 与 Boost.Serialization 混用冲突二者可共存注意命名空间隔离同一类型不要同时给两个库定义序列化逻辑10官方版本较旧1.3.x是否支持 C20 类型1.3.2 起支持 std::optional、std::variant、std::string_view只读C20 ranges 需自行封装11如何让 cereal 支持自定义容器特化 cereal::traits::is_output_serializable 等 traits或直接为容器写 serialize 自由函数12线程安全cereal 的 Archive 对象非线程安全不同线程各持自己的 Archive 与流即可共享数据需外部加锁一句话选型建议C 内部、快速、零依赖地持久化对象 → cereal跨语言强约束协议 → Protobuf超高频只读零拷贝 → flatbuffers批量列式分析交换 → Apache Arrow纯 JSON 文本处理 → nlohmann/json / simdjson。7. 总结cereal 的价值不在于性能最强或功能最全而在于它把序列化任意 C 类型这件事的仪式成本降到了最低没有代码生成器、没有 IDL、没有重依赖一个 serialize 模板函数加三行头文件即可覆盖从配置持久化到游戏存档的大多数内部需求。配合版本化与分支 Archive它甚至能在长期演进的项目中维持稳定的向后兼容。如果你的团队正在为一个纯 C 项目寻找今天下午就能用上的序列化方案cereal 就是那个答案。